@colin4k1024/tsp 2.4.1 → 2.4.3

package/scripts/install-open-design.js

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const DEFAULT_REPO_URL = 'https://github.com/nexu-io/open-design.git';
+const DEFAULT_INSTALL_DIR = path.join(os.homedir(), '.tsp', 'open-design');
+const DEFAULT_REF = 'main';
+
+function parseArgs(argv) {
+  const parsed = {
+    installDir: process.env.TSP_OPEN_DESIGN_HOME || process.env.OPEN_DESIGN_HOME || DEFAULT_INSTALL_DIR,
+    repoUrl: process.env.TSP_OPEN_DESIGN_REPO || DEFAULT_REPO_URL,
+    ref: process.env.TSP_OPEN_DESIGN_REF || DEFAULT_REF,
+    skipDeps: process.env.TSP_OPEN_DESIGN_SKIP_DEPS === '1',
+    dryRun: false,
+  };
+
+  for (let index = 2; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--dir') {
+      parsed.installDir = argv[index + 1] || parsed.installDir;
+      index += 1;
+      continue;
+    }
+    if (arg === '--repo') {
+      parsed.repoUrl = argv[index + 1] || parsed.repoUrl;
+      index += 1;
+      continue;
+    }
+    if (arg === '--ref') {
+      parsed.ref = argv[index + 1] || parsed.ref;
+      index += 1;
+      continue;
+    }
+    if (arg === '--skip-deps') {
+      parsed.skipDeps = true;
+      continue;
+    }
+    if (arg === '--dry-run') {
+      parsed.dryRun = true;
+      continue;
+    }
+    if (arg === '--help' || arg === '-h') {
+      parsed.help = true;
+      continue;
+    }
+    throw new Error(`Unknown argument: ${arg}`);
+  }
+
+  parsed.installDir = path.resolve(parsed.installDir);
+  return parsed;
+}
+
+function printHelp() {
+  console.log(`
+Install or update Open Design for TSP.
+
+Usage:
+  node scripts/install-open-design.js [--dir <path>] [--repo <url>] [--ref <git-ref>] [--skip-deps] [--dry-run]
+
+Environment:
+  TSP_OPEN_DESIGN_HOME       Override install directory. Default: ~/.tsp/open-design
+  TSP_OPEN_DESIGN_REPO       Override upstream repository URL.
+  TSP_OPEN_DESIGN_REF        Override git ref. Default: main
+  TSP_OPEN_DESIGN_SKIP_DEPS  Set to 1 to skip pnpm dependency install.
+`);
+}
+
+function commandExists(command) {
+  const result = spawnSync(command, ['--version'], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'ignore', 'ignore'],
+  });
+  return result.status === 0;
+}
+
+function run(command, args, options = {}) {
+  const printable = [command, ...args].join(' ');
+  if (options.dryRun) {
+    console.log(`[dry-run] ${printable}`);
+    return;
+  }
+
+  const result = spawnSync(command, args, {
+    cwd: options.cwd || process.cwd(),
+    encoding: 'utf8',
+    stdio: options.quiet ? ['ignore', 'pipe', 'pipe'] : 'inherit',
+  });
+
+  if (result.status !== 0) {
+    const stderr = result.stderr ? `\n${result.stderr.trim()}` : '';
+    throw new Error(`Command failed: ${printable}${stderr}`);
+  }
+}
+
+function readGitRemote(installDir) {
+  const result = spawnSync('git', ['-C', installDir, 'remote', 'get-url', 'origin'], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+  });
+  return result.status === 0 ? result.stdout.trim() : null;
+}
+
+function isOpenDesignRemote(remoteUrl, expectedRepoUrl) {
+  const normalized = String(remoteUrl || '').replace(/\.git$/, '');
+  const expected = String(expectedRepoUrl || '').replace(/\.git$/, '');
+  return normalized === expected || normalized.endsWith('/nexu-io/open-design');
+}
+
+function ensureOpenDesignCheckout(options) {
+  const gitDir = path.join(options.installDir, '.git');
+  if (!fs.existsSync(options.installDir)) {
+    console.log(`Installing Open Design into ${options.installDir}`);
+    if (!options.dryRun) {
+      fs.mkdirSync(path.dirname(options.installDir), { recursive: true });
+    }
+    run('git', [
+      'clone',
+      '--depth',
+      '1',
+      '--branch',
+      options.ref,
+      options.repoUrl,
+      options.installDir,
+    ], { dryRun: options.dryRun });
+    return;
+  }
+
+  if (!fs.existsSync(gitDir)) {
+    throw new Error(`Open Design install path exists but is not a git checkout: ${options.installDir}`);
+  }
+
+  const remoteUrl = readGitRemote(options.installDir);
+  if (!isOpenDesignRemote(remoteUrl, options.repoUrl)) {
+    throw new Error(
+      `Refusing to update ${options.installDir}; origin is ${remoteUrl || '(unknown)'}, expected ${options.repoUrl}`
+    );
+  }
+
+  console.log(`Updating Open Design at ${options.installDir}`);
+  run('git', ['-C', options.installDir, 'fetch', '--depth', '1', 'origin', options.ref], {
+    dryRun: options.dryRun,
+  });
+  run('git', ['-C', options.installDir, 'checkout', 'FETCH_HEAD'], {
+    dryRun: options.dryRun,
+  });
+}
+
+function installDependencies(options) {
+  if (options.skipDeps) {
+    console.log('Skipping Open Design dependency install because --skip-deps or TSP_OPEN_DESIGN_SKIP_DEPS=1 is set.');
+    return;
+  }
+
+  if (!commandExists('corepack')) {
+    console.warn(
+      'Open Design source is installed, but corepack/pnpm is not available. '
+      + 'Install Node 24 with corepack, then run `corepack enable && pnpm install` in the Open Design directory.'
+    );
+    return;
+  }
+
+  run('corepack', ['enable'], {
+    cwd: options.installDir,
+    dryRun: options.dryRun,
+  });
+
+  if (!commandExists('pnpm')) {
+    console.warn(
+      'Open Design source is installed, but pnpm is still not available after `corepack enable`. '
+      + 'Run `corepack prepare pnpm@10.33.2 --activate && pnpm install` in the Open Design directory.'
+    );
+    return;
+  }
+
+  run('pnpm', ['install'], {
+    cwd: options.installDir,
+    dryRun: options.dryRun,
+  });
+}
+
+function main() {
+  try {
+    const options = parseArgs(process.argv);
+    if (options.help) {
+      printHelp();
+      return;
+    }
+
+    if (!commandExists('git')) {
+      throw new Error('git is required to install Open Design');
+    }
+
+    ensureOpenDesignCheckout(options);
+    installDependencies(options);
+    console.log(`Open Design ready: ${options.installDir}`);
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+main();

package/scripts/install-plan.js

@@ -183,6 +183,23 @@ function printPlan(plan) {
       );
     }
   }
+
+  const externalInstalls = plan.selectedModules
+    .map(module => ({ module, externalInstall: module.externalInstall }))
+    .filter(({ externalInstall }) => externalInstall && typeof externalInstall === 'object' && !Array.isArray(externalInstall))
+    .filter(({ externalInstall }) => {
+      const profiles = Array.isArray(externalInstall.profiles)
+        ? externalInstall.profiles.map(value => String(value).trim()).filter(Boolean)
+        : [];
+      return profiles.length === 0 || profiles.includes(plan.profileId);
+    });
+  if (externalInstalls.length > 0) {
+    console.log('');
+    console.log(`External install plan (${externalInstalls.length}):`);
+    for (const { module, externalInstall } of externalInstalls) {
+      console.log(`- ${externalInstall.id || module.id}: ${externalInstall.description || externalInstall.script}`);
+    }
+  }
 }
 
 function main() {

package/scripts/lib/install/apply.js

@@ -2,6 +2,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const { spawnSync } = require('child_process');
 
 const { writeInstallState } = require('../install-state');
 const { writeInstallAuditManifest } = require('../install-audit-manifest');
@@ -176,6 +177,32 @@ function buildMergedSettings(plan) {
   };
 }
 
+function runExternalInstall(externalInstall) {
+  const args = [];
+  if (externalInstall.scriptPath) {
+    args.push(externalInstall.scriptPath);
+  } else if (externalInstall.script) {
+    args.push(externalInstall.script);
+  }
+  if (Array.isArray(externalInstall.args)) {
+    args.push(...externalInstall.args);
+  }
+
+  const command = externalInstall.command || 'node';
+  const label = externalInstall.id || externalInstall.moduleId || command;
+  console.log(`Running external install: ${label}`);
+
+  const result = spawnSync(command, args, {
+    cwd: externalInstall.cwd || process.cwd(),
+    encoding: 'utf8',
+    stdio: 'inherit',
+  });
+
+  if (result.status !== 0) {
+    throw new Error(`External install failed: ${label}`);
+  }
+}
+
 function applyInstallPlan(plan) {
   const mergedSettingsPlan = buildMergedSettings(plan);
 
@@ -199,6 +226,10 @@ function applyInstallPlan(plan) {
     );
   }
 
+  for (const externalInstall of Array.isArray(plan.externalInstalls) ? plan.externalInstalls : []) {
+    runExternalInstall(externalInstall);
+  }
+
   writeInstallState(plan.installStatePath, plan.statePreview);
   const { installManifestPath } = writeInstallAuditManifest(plan);
 

package/scripts/lib/install-executor.js

@@ -133,6 +133,56 @@ function createStatePreview(options) {
   return createInstallState(options);
 }
 
+function resolveExternalInstalls(selectedModules, options = {}) {
+  const profileId = options.profileId || null;
+  const sourceRoot = options.sourceRoot || getSourceRoot();
+  const target = options.target || null;
+  const installs = [];
+
+  for (const module of selectedModules) {
+    const externalInstall = module && module.externalInstall;
+    if (!externalInstall || typeof externalInstall !== 'object' || Array.isArray(externalInstall)) {
+      continue;
+    }
+
+    const profileFilter = Array.isArray(externalInstall.profiles)
+      ? externalInstall.profiles.map(value => String(value).trim()).filter(Boolean)
+      : [];
+    if (profileFilter.length > 0 && (!profileId || !profileFilter.includes(profileId))) {
+      continue;
+    }
+
+    const command = typeof externalInstall.command === 'string' && externalInstall.command.trim()
+      ? externalInstall.command.trim()
+      : 'node';
+    const script = typeof externalInstall.script === 'string' && externalInstall.script.trim()
+      ? externalInstall.script.trim()
+      : null;
+    const args = Array.isArray(externalInstall.args)
+      ? externalInstall.args.map(value => String(value))
+      : [];
+
+    if (!script) {
+      throw new Error(`Install module ${module.id} has externalInstall but no script`);
+    }
+
+    installs.push({
+      id: externalInstall.id || module.id,
+      moduleId: module.id,
+      description: externalInstall.description || '',
+      command,
+      script,
+      scriptPath: path.join(sourceRoot, script),
+      args,
+      cwd: sourceRoot,
+      target,
+      profileId,
+    });
+  }
+
+  return installs;
+}
+
 function applyInstallPlan(plan) {
   const { applyInstallPlan: applyPlan } = require('./install/apply');
   return applyPlan(plan);
@@ -617,6 +667,11 @@ function createManifestInstallPlan(options = {}) {
   });
   const adapter = getInstallTargetAdapter(target);
   const operations = plan.operations.flatMap(operation => materializeScaffoldOperation(sourceRoot, operation));
+  const externalInstalls = resolveExternalInstalls(plan.selectedModules, {
+    profileId: plan.profileId,
+    sourceRoot,
+    target,
+  });
   const source = {
     repoVersion: getPackageVersion(sourceRoot),
     repoCommit: getRepoCommit(sourceRoot),
@@ -667,6 +722,7 @@ function createManifestInstallPlan(options = {}) {
     skippedModuleIds: plan.skippedModuleIds,
     excludedModuleIds: plan.excludedModuleIds,
     operations,
+    externalInstalls,
     statePreview,
   };
 }

package/skills/open-design/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: open-design
+description: >
+  Use Open Design as an external local-first design workbench for prototypes,
+  decks, mobile screens, dashboards, DESIGN.md systems, and exportable visual
+  artifacts. Keep TSP responsible for team workflow, handoff, and quality gates.
+origin: nexu-io/open-design (reference-only controlled integration)
+---
+
+# Open Design
+
+## 用途
+
+- 用 Open Design 生成或迭代高保真视觉 artifacts：web prototype、dashboard、mobile flow、deck、poster、social carousel、runbook/spec 类页面。
+- 在前端任务中把 `DESIGN.md`、设计方向、skill、preview 和 export 结果作为证据回落到 TSP 主链。
+- 让 `product-manager`、`frontend-engineer`、`qa-engineer` 在同一套可预览 artifact 上讨论，而不是只靠文字描述。
+
+## 触发信号
+
+- 用户要“像 Claude Design 那样”快速生成可编辑原型、deck、营销页、移动界面或设计系统。
+- 需求还没有稳定视觉方向，需要先通过表单、方向 picker 或 `DESIGN.md` 锁定风格。
+- `/team-plan` 或 `/team-execute` 进入 UI 实施前，需要可截图、可导出、可评审的设计证据。
+- `/team-review` 需要对 artifact 做视觉、响应式、可访问性、反 AI 味、导出完整性检查。
+
+## 默认工作流
+
+1. 先完成 TSP 侧任务收敛：
+   - 目标、受众、页面/屏幕范围、数据真实性、品牌约束、响应式范围、A11y/性能门禁。
+   - 若任务来自 `/team-*`，把这些约束写入 artifact 或 handoff，不只留在聊天里。
+2. 检查目标项目是否已有 `DESIGN.md`：
+   - 有：把它作为 Open Design 的 active design system 或直接放入 OD 项目工作目录。
+   - 无：先用 `frontend-ui-ux-system` 或 OD 的 design-system 能力生成候选 `DESIGN.md`。
+3. 若用户安装的是 TSP `full` profile，Open Design 默认会由 TSP 安装器准备到 `~/.tsp/open-design`；否则在独立 Open Design checkout 中运行上游工具，不在 TSP 仓库里启动 OD daemon：
+   ```bash
+   # full profile 自动路径
+   cd ~/.tsp/open-design
+
+   # 手动路径
+   git clone https://github.com/nexu-io/open-design.git
+   cd open-design
+   corepack enable
+   pnpm install
+   pnpm tools-dev
+   ```
+4. 在 OD 中选择合适 surface：
+   - prototype：`web-prototype`、`saas-landing`、`dashboard`、`mobile-app` 等。
+   - deck：`guizang-ppt`、`simple-deck`、`weekly-update` 等。
+   - document-like：`pm-spec`、`eng-runbook`、`finance-report`、`team-okrs` 等。
+5. 生成后把关键产物回落到 TSP：
+   - artifact 路径或导出文件
+   - 使用的 OD skill、design system、visual direction
+   - 约束与自检结论
+   - 对 `/team-plan`、`/team-execute`、`/team-review` 或 `/team-release` 的决策影响
+6. 若 artifact 会进入实现，frontend 角色必须继续执行 TSP 前端门禁：
+   - 响应式、键盘访问、对比度、性能、加载/空态/错误态
+   - 真实数据与授权素材检查
+   - 不能把 OD 输出直接视为生产代码完成
+
+## 输出约定
+
+- TSP 侧只沉淀集成证据，不复制 Open Design 源码或生成数据库。
+- 推荐在消费方项目中落盘：
+  - `docs/artifacts/<date>-open-design-brief.md`
+  - `docs/artifacts/<date>-open-design-review.md`
+  - 需要长期复用时，将最终 `DESIGN.md` 放在项目根目录或设计文档目录。
+- 最小交付字段：
+  - 任务目标
+  - 使用的 OD skill / design system / visual direction
+  - 产物路径或导出格式
+  - 主要设计决策及证据
+  - 风险、未验证项、下一步 TSP 命令
+
+## 边界与禁用项
+
+- 只有 TSP `full` profile 会自动 clone/update Open Design；其他 profile 只安装 TSP 侧 skill/runbook。
+- 不把 Open Design 当作 TSP 的默认 npm 依赖；它要求独立 Node/pnpm/daemon 生命周期。
+- 不在本仓库 vendoring Open Design 的 `skills/`、`design-systems/`、daemon、web app 或 SQLite 数据。
+- 不把 OD 的视觉结果绕过 `/team-review` 直接发布。
+- 不使用未授权品牌素材、字体、截图或第三方图片作为可分发 artifact。
+- 不在 TSP 管理仓库中运行会改写本仓库 hooks、AGENTS 或 MCP 契约的外部 setup 命令。
+
+## 推荐组合
+
+- 需求到原型：`/team-intake -> frontend-ui-ux-system -> open-design -> /team-plan`
+- UI 实施：`/team-execute -> open-design artifact evidence -> frontend-engineering -> /handoff`
+- 视觉评审：`/team-review -> open-design artifact review -> browser-smoke-testing`
+- Deck / 汇报材料：`frontend-slides -> open-design deck mode -> /team-release`

package/skills/open-design/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Open Design"
+  short_description: "用 Open Design 生成和评审本地优先设计 artifact"
+  default_prompt: "Use $open-design when a TSP task needs local-first prototypes, decks, dashboards, mobile flows, DESIGN.md systems, or exportable visual artifacts. Keep Open Design external, avoid vendoring upstream runtime assets, and feed artifact evidence back into /team-plan, /team-execute, or /team-review."