tea-sdlc/scripts/install.js

/**
 * 轉接檔的產生與移除。全專案唯一知道各平台目錄結構的地方。
 *
 * 轉接檔裡沒有路徑，只有一句「執行 tea-sdlc prompt --name <指令名>」。正本在哪由
 * PATH 上的 tea-sdlc 自己回推，所以升級 Node、換版本管理器、改 npm prefix 都不會讓
 * 七個平台的轉接檔同時指向不存在的檔案。
 *
 * 用法（由 bin/tea-sdlc.js 轉入）：
 *   tea-sdlc install   [--platform a,b] [--dry-run]
 *   tea-sdlc uninstall [--platform a,b] [--dry-run]
 */
import {
  existsSync,
  mkdirSync,
  readFileSync,
  readdirSync,
  readSync,
  rmSync,
  statSync,
  writeFileSync,
} from 'node:fs';
import { homedir } from 'node:os';
import { basename, dirname, join } from 'node:path';
import {
  ScriptError,
  checkPluginLayout,
  missingBinaries,
  packageVersion,
  parseFlags,
  promptsDir,
} from './lib.js';

/**
 * 七個平台。`detect` 是「這台機器裝了它沒有」的判準，`target` 是轉接檔的落點，
 * 兩者都相對於 `base`——`home` 是家目錄，`cwd` 是目前的專案（Copilot 讀的是 repo 內的
 * .github/，不是家目錄）。
 *
 * `kind` 決定轉接檔長什麼樣：`command` 的四個平台吃 commands/<名>.md，
 * `skill` 的三個平台吃 skills/<名>/SKILL.md。
 *
 * 已接受的取捨：Antigravity、Copilot、Kiro 無法關閉自動觸發，只能靠窄化 description
 * 降低誤觸；四個 command 平台則實際設上旗標。
 */
const PLATFORMS = [
  { name: 'claude', label: 'Claude Code', base: 'home', detect: ['.claude'], target: ['.claude', 'commands'], kind: 'command' },
  { name: 'codex', label: 'Codex', base: 'home', detect: ['.codex'], target: ['.codex', 'prompts'], kind: 'command' },
  { name: 'opencode', label: 'OpenCode', base: 'home', detect: ['.config', 'opencode'], target: ['.config', 'opencode', 'command'], kind: 'command' },
  { name: 'oh-my-pi', label: 'oh-my-pi', base: 'home', detect: ['.omp'], target: ['.omp', 'commands'], kind: 'command' },
  { name: 'antigravity', label: 'Antigravity', base: 'home', detect: ['.gemini'], target: ['.gemini', 'skills'], kind: 'skill' },
  { name: 'kiro', label: 'Kiro', base: 'home', detect: ['.kiro'], target: ['.kiro', 'skills'], kind: 'skill' },
  { name: 'copilot', label: 'GitHub Copilot', base: 'cwd', detect: ['.github'], target: ['.github', 'skills'], kind: 'skill' },
];

/**
 * 產生標記。它同時是三件事的依據：
 *   1. 這個檔是不是我們產生的——移除時只刪帶標記的，使用者自己寫的同名檔一律留著
 *   2. 是哪一版產生的——status 靠它判斷過時
 *   3. 給讀到檔案的人一句「別手改這裡」
 */
const MARKER = 'tea-sdlc-adapter';
const MARKER_RE = new RegExp(`<!-- ${MARKER} v([^\\s：]+)`);

/**
 * 兩種轉接檔形式的差別全部收在這裡：檔案擺哪、怎麼把已經擺好的找回來、
 * frontmatter 要不要多一行、刪完要不要收殼。散在四個 if 裡的話，日後多一種形式
 * 就得在四個地方各改一次，而漏掉哪一個不會有人發現。
 */
const KINDS = {
  /** 一個指令一個檔：<目錄>/<指令名>.md */
  command: {
    path: (dir, name) => join(dir, `${name}.md`),
    list: (dir) => readdirSync(dir).map((entry) => join(dir, entry)),
    // 支援關閉自動觸發的平台就關掉
    frontmatter: ['disable-model-invocation: true'],
    cleanup: () => {},
  },
  /** 一個指令一層目錄：<目錄>/<指令名>/SKILL.md */
  skill: {
    path: (dir, name) => join(dir, name, 'SKILL.md'),
    list: (dir) => readdirSync(dir).map((entry) => join(dir, entry, 'SKILL.md')),
    // 這三個平台關不掉自動觸發，只能靠 description 已經窄到不會被誤判
    frontmatter: [],
    cleanup: (path) => rmEmptyDir(dirname(path)),
  },
};


// ── 產生 ───────────────────────────────────────────────────────────

/**
 * @param {string[]} argv bin 取走子指令之後剩下的參數
 * @returns {object} 放進 data 的內容
 */
export function runInstall(argv) {
  const flags = parseFlags(argv, { optional: ['platform'], booleans: ['dry-run'] });

  // 只警告不中止：缺 tea 完全不影響轉接檔產生，硬擋等於逼使用者為了裝 plugin 先去裝 tea。
  // 但完全不查也不行——安裝是一次性動作，使用者裝完就走，沒被提醒他會以為一切就緒。
  const { missing, hint } = missingBinaries(['node', 'git', 'tea']);

  const prompts = readPrompts();
  const version = packageVersion();
  const chosen = choose(flags.platform);

  const platforms = chosen.map((platform) => {
    const files = prompts.map((prompt) => ({
      path: adapterPath(platform, prompt.name),
      text: adapterText(platform, prompt, version),
    }));
    if (!flags['dry-run']) {
      for (const file of files) {
        mkdirSync(dirname(file.path), { recursive: true });
        writeFileSync(file.path, file.text);
      }
    }
    return { name: platform.name, kind: platform.kind, adapters: files.map((file) => file.path) };
  });

  return {
    dryRun: flags['dry-run'] === true,
    version,
    commands: prompts.map((prompt) => prompt.name),
    platforms,
    missingBinaries: missing,
    warning: hint === '' ? null : hint,
  };
}


// ── 移除 ───────────────────────────────────────────────────────────

/**
 * 只移除轉接檔，正本一動不動——正本在套件裡，這支腳本連碰都不碰它。
 * 平台自己的 commands/、skills/ 目錄也留著：那不是我們建的東西。
 */
export function runUninstall(argv) {
  const flags = parseFlags(argv, { optional: ['platform'], booleans: ['dry-run'] });
  const requested = flags.platform === undefined ? null : parsePlatformFlag(flags.platform);

  const removed = [];
  const kept = [];

  // 與 install 不同，這裡不要求平台偵測得到：平台被移掉之後留下的轉接檔更需要清，
  // 而掃一個不存在的目錄本來就沒有東西可刪，不需要為此報錯。
  for (const platform of PLATFORMS) {
    if (requested && !requested.includes(platform.name)) continue;

    for (const path of adaptersUnder(platform)) {
      // 逐版累積的舊轉接檔也要清掉，所以掃的是目錄而不是這一版的指令清單
      if (adapterVersion(path) === null) {
        kept.push({ path, reason: `不是 tea-sdlc 產生的（沒有 ${MARKER} 標記）` });
        continue;
      }
      removed.push(path);
      if (flags['dry-run']) continue;

      rmSync(path);
      KINDS[platform.kind].cleanup(path);
    }
  }

  return { dryRun: flags['dry-run'] === true, removed, kept };
}


// ── 現況 ───────────────────────────────────────────────────────────

/**
 * 各平台的轉接檔現況，供 status 回報。平台目錄結構的知識只有這一份，
 * status 不複製一份自己的。
 * @returns {{name: string, kind: string, detected: boolean, adapters: number, versions: string[], stale: boolean}[]}
 */
export function platformReport() {
  const current = packageVersion();
  const expected = countPrompts();

  return PLATFORMS.map((platform) => {
    const versions = adaptersUnder(platform).map(adapterVersion).filter((v) => v !== null);

    return {
      name: platform.name,
      kind: platform.kind,
      dir: pathOf(platform, platform.target),
      detected: existsSync(pathOf(platform, platform.detect)),
      adapters: {
        // 應該裝幾份 vs 實際裝了幾份：少了就是有指令沒佈署到
        expected,
        present: versions.length,
        stale: versions.some((version) => version !== current),
      },
    };
  });
}


// ── 平台挑選 ───────────────────────────────────────────────────────

/**
 * 決定要動哪些平台。三條路：`--platform` 指名、TTY 上勾選、非互動時全裝。
 * 指名了沒裝的平台要擋下來——那多半是打錯字，替它建目錄只會在機器上留下孤兒。
 */
function choose(flag) {
  const detected = PLATFORMS.filter((platform) => existsSync(pathOf(platform, platform.detect)));

  if (flag !== undefined) {
    const names = parsePlatformFlag(flag);
    const missing = names.filter((name) => !detected.some((platform) => platform.name === name));
    if (missing.length > 0) {
      throw new ScriptError(
        'PLATFORM_NOT_DETECTED',
        `這台機器上偵測不到 ${missing.join('、')}；若確定要裝，請先把該平台裝起來再重跑`,
      );
    }
    return PLATFORMS.filter((platform) => names.includes(platform.name));
  }

  if (detected.length === 0) {
    throw new ScriptError(
      'NO_PLATFORM_DETECTED',
      `偵測不到任何 agent 平台（找過 ${PLATFORMS.map(detectLabel).join('、')}）；` +
        '請先安裝其中至少一個，或用 --platform 指名',
    );
  }
  // CI 與腳本一律不進互動提示：沒有 TTY 就照預設全裝
  return process.stdin.isTTY ? select(detected) : detected;
}

/** `--platform a,b` 的值。認不得的名字要當場指出來，不要默默少裝一個。 */
function parsePlatformFlag(value) {
  const names = String(value)
    .split(',')
    .map((name) => name.trim())
    .filter((name) => name !== '');

  const known = PLATFORMS.map((platform) => platform.name);
  const unknown = names.filter((name) => !known.includes(name));
  if (names.length === 0 || unknown.length > 0) {
    throw new ScriptError(
      'UNKNOWN_PLATFORM',
      `不認得的平台 ${unknown.join('、') || '（空值）'}；可用的是：${known.join('、')}`,
    );
  }
  return names;
}

/**
 * 在終端機上列出偵測到的平台讓人勾選，預設全勾。
 * 問句走 stderr：stdout 是給呼叫端讀的單行 JSON，不能混進人看的字。
 */
function select(detected) {
  process.stderr.write('要安裝到哪些平台？\n');
  for (const line of checklist(detected)) process.stderr.write(`${line}\n`);

  return selectPlatforms(detected, readLine('直接按 Enter 全裝，或輸入要裝的編號／名稱（逗號分隔）：'));
}

/** 勾選清單的每一行。預設全勾，所以每一項都是 [x]。 */
export function checklist(detected) {
  return detected.map((platform, i) => `  [x] ${i + 1}. ${platform.label}（${platform.name}）`);
}

/**
 * 把使用者打的那一行變成要安裝的平台。空字串是「全部」——預設全勾，直接按 Enter 就過。
 * 與 I/O 分開是為了測得到：真的開一個 TTY 來測這段，測的會是 pty 而不是這個規則。
 * @param {object[]} detected 剛才列出來的平台，順序即編號
 * @param {string} answer 使用者打的那一行
 */
export function selectPlatforms(detected, answer) {
  if (answer.trim() === '') return detected;

  const picked = answer
    .split(',')
    .map((token) => token.trim())
    .filter((token) => token !== '')
    .map((token) => {
      const byIndex = /^\d+$/.test(token) ? detected[Number(token) - 1] : undefined;
      const platform = byIndex ?? detected.find((candidate) => candidate.name === token);
      if (!platform) {
        throw new ScriptError('UNKNOWN_PLATFORM', `勾選的 ${token} 不在剛才列出的平台裡`);
      }
      return platform;
    });

  return detected.filter((platform) => picked.includes(platform));
}

/**
 * 從 stdin 讀一行。非同步讀在這裡沒有用武之地——問完就要等答案，後面什麼都不能做。
 * EAGAIN 是 TTY 還沒有東西可讀，等一下再試，不要空轉燒 CPU。
 */
function readLine(question) {
  process.stderr.write(question);
  const buffer = Buffer.alloc(256);
  let answer = '';

  while (!answer.includes('\n')) {
    let read;
    try {
      read = readSync(0, buffer, 0, buffer.length, null);
    } catch (error) {
      if (error.code !== 'EAGAIN') throw error;
      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 20);
      continue;
    }
    if (read === 0) break;
    answer += buffer.toString('utf8', 0, read);
  }
  process.stderr.write('\n');
  return answer.split('\n')[0].trim();
}


// ── 轉接檔 ─────────────────────────────────────────────────────────

/**
 * 產生一份轉接檔。內容就是一句指向 tea-sdlc 的話：正本只有一份，改規則不會出現
 * 各平台版本分歧，也不必為了改規則重跑安裝。
 */
function adapterText(platform, prompt, version) {
  const front = [
    '---',
    `name: ${prompt.name}`,
    `description: ${prompt.description}`,
    ...KINDS[platform.kind].frontmatter,
    '---',
  ];

  return [
    ...front,
    '',
    `<!-- ${MARKER} v${version}：由 tea-sdlc install 產生，請勿手動編輯。`,
    '     改流程請改流程正本（不必重裝）；指令數量變了才需要重跑 tea-sdlc install。 -->',
    '',
    `執行 \`tea-sdlc prompt --name ${prompt.name} --adapter-version ${version}\`，` +
      '並完全遵照它印出的內容執行。',
    '',
  ].join('\n');
}

/** 轉接檔的落點 */
function adapterPath(platform, name) {
  return KINDS[platform.kind].path(pathOf(platform, platform.target), name);
}

/** 這個平台的目標目錄底下，所有長得像轉接檔的檔案（還沒判斷是不是我們產生的） */
function adaptersUnder(platform) {
  const dir = pathOf(platform, platform.target);
  if (!isDir(dir)) return [];

  return KINDS[platform.kind].list(dir).filter(isFile).sort();
}

/**
 * 這個檔是我們哪一版產生的；沒有標記就回 null。
 * 「是不是我們的」與「是哪一版」是同一次讀檔的兩個答案，分成兩支函式會讓每份轉接檔被讀兩次。
 * @returns {string|null}
 */
function adapterVersion(path) {
  return readFileSync(path, 'utf8').match(MARKER_RE)?.[1] ?? null;
}


// ── 流程正本 ───────────────────────────────────────────────────────

/**
 * 有哪些指令可以裝。以 prompts/ 裡實際存在的正本為準，不是寫死的六個名字——
 * 裝出一個指向不存在正本的轉接檔，使用者只會看到 PROMPT_NOT_FOUND。
 * @returns {{name: string, description: string}[]}
 */
function readPrompts() {
  checkPluginLayout();

  const prompts = readdirSync(promptsDir())
    .filter((entry) => entry.endsWith('.md'))
    .sort()
    .map((entry) => {
      const name = basename(entry, '.md');
      const text = readFileSync(join(promptsDir(), entry), 'utf8');
      const description = text.match(/^description:\s*(.+)$/m)?.[1]?.trim();
      if (!description) {
        throw new ScriptError(
          'PROMPT_NO_DESCRIPTION',
          `流程正本 ${entry} 沒有 description 那一行，轉接檔沒有東西可抄`,
        );
      }
      // 前綴是這套指令「不自動觸發」的最後一道防線：三個平台關不掉自動觸發，
      // 全靠這句把 description 窄到不會被誤判。抄過去之前就要擋，不能等使用者發現誤觸。
      const prefix = `僅由 /${name} 指令叫用。`;
      if (!description.startsWith(prefix)) {
        throw new ScriptError(
          'PROMPT_BAD_DESCRIPTION',
          `流程正本 ${entry} 的 description 必須以「${prefix}」起頭，目前是：${description}`,
        );
      }
      return { name, description };
    });

  if (prompts.length === 0) {
    throw new ScriptError('NO_PROMPTS', `${promptsDir()} 裡沒有任何流程正本，沒有東西可以佈署`);
  }
  return prompts;
}

/**
 * 應該裝幾份轉接檔。status 只要數量，不該為了數數就因為某份正本的 description
 * 寫壞而整支失敗——回報現況的指令不該比被回報的東西更容易倒。
 */
function countPrompts() {
  try {
    return readdirSync(promptsDir()).filter((entry) => entry.endsWith('.md')).length;
  } catch {
    return 0;
  }
}


// ── 路徑小工具 ─────────────────────────────────────────────────────

function pathOf(platform, segments) {
  return join(platform.base === 'home' ? homedir() : process.cwd(), ...segments);
}

/** 偵測目錄的人類可讀寫法，例如 ~/.claude */
function detectLabel(platform) {
  return `${platform.base === 'home' ? '~/' : './'}${platform.detect.join('/')}`;
}

function rmEmptyDir(dir) {
  if (readdirSync(dir).length === 0) rmSync(dir, { recursive: true });
}

function isDir(path) {
  return existsSync(path) && statSync(path).isDirectory();
}

function isFile(path) {
  return existsSync(path) && statSync(path).isFile();
}