specline 1.4.0 → 2.0.1

package/lib/platforms.mjs

@@ -0,0 +1,74 @@
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * Parse a simple YAML list from platforms.yaml.
+ * Handles both inline `[cursor, claude]` and block `- cursor` formats.
+ * @param {string} content
+ * @returns {string[]}
+ */
+export function parsePlatformsYaml(content) {
+  const platforms = [];
+  const lines = content.split('\n');
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed === '' || trimmed.startsWith('#')) continue;
+
+    if (trimmed.startsWith('- ')) {
+      platforms.push(trimmed.slice(2).trim().replace(/^["']|["']$/g, ''));
+      continue;
+    }
+
+    const inlineMatch = trimmed.match(/^platforms:\s*\[(.+)\]/);
+    if (inlineMatch) {
+      return inlineMatch[1]
+        .split(',')
+        .map((p) => p.trim().replace(/^["']|["']$/g, ''))
+        .filter(Boolean);
+    }
+
+    if (trimmed.startsWith('platforms:')) continue;
+  }
+
+  return platforms;
+}
+
+/**
+ * Read the platforms list from specline/platforms.yaml
+ * @param {string} projectDir
+ * @returns {string[]}
+ */
+export function readPlatforms(projectDir) {
+  const platformsPath = join(projectDir, 'specline', 'platforms.yaml');
+  if (!existsSync(platformsPath)) return [];
+  const content = readFileSync(platformsPath, 'utf-8');
+  return parsePlatformsYaml(content);
+}
+
+/**
+ * CLI entry point for `specline platforms`
+ * @param {string} [cwd]
+ * @returns {number} exit code
+ */
+export function cliPlatforms(cwd) {
+  const projectDir = cwd || process.cwd();
+  const platformsPath = join(projectDir, 'specline', 'platforms.yaml');
+
+  if (!existsSync(platformsPath)) {
+    process.stderr.write('No specline/platforms.yaml found. Run `specline init` first.\n');
+    return 1;
+  }
+
+  const platforms = readPlatforms(projectDir);
+  if (platforms.length === 0) {
+    process.stdout.write('No platforms configured.\n');
+    return 0;
+  }
+
+  process.stdout.write('Deployed platforms:\n');
+  for (const p of platforms) {
+    process.stdout.write(`  - ${p}\n`);
+  }
+  return 0;
+}

package/lib/render-agents.mjs

@@ -0,0 +1,88 @@
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import { PACKAGE_ROOT } from './paths.mjs';
+
+/**
+ * @param {string} yamlContent
+ * @returns {{ name: string, description: string, instructions: string }}
+ */
+export function parseAgentYaml(yamlContent) {
+  const lines = yamlContent.split('\n');
+  const fields = { name: '', description: '', instructions: '' };
+  let current = '';
+  const block = [];
+
+  for (const line of lines) {
+    if (line.match(/^name:\s/)) {
+      current = 'name';
+      fields.name = line.replace(/^name:\s*"?/, '').replace(/"$/, '').trim();
+    } else if (line.match(/^description:\s/)) {
+      current = 'description';
+      const remainder = line.replace(/^description:\s*"?/, '').replace(/"$/, '').trim();
+      if (/^[>|][-+]?$/.test(remainder)) {
+        // Multi-line block scalar (e.g. >-, |, >+, |-)
+        block.length = 0;
+        fields.description = '';
+      } else {
+        fields.description = remainder;
+      }
+    } else if (line.match(/^instructions:\s*\|\s*$/)) {
+      // Save collected description block before switching to instructions
+      if (current === 'description' && block.length > 0) {
+        fields.description = block.join(' ').trim();
+        block.length = 0;
+      }
+      current = 'instructions';
+    } else if (current === 'description') {
+      const trimmed = line.trim();
+      if (trimmed.length > 0) block.push(trimmed);
+    } else if (current === 'instructions') {
+      block.push(line.replace(/^  /, ''));
+    } else if (line.match(/^(output|constraints|phases):/)) {
+      current = '';
+    }
+  }
+
+  // Handle description at end-of-file
+  if (current === 'description' && block.length > 0) {
+    fields.description = block.join(' ').trim();
+  }
+
+  fields.instructions = block.join('\n').trim();
+  return fields;
+}
+
+/** @param {string} yamlContent */
+export function renderCursorAgent(yamlContent) {
+  const { name, description, instructions } = parseAgentYaml(yamlContent);
+  return `---\nname: ${name}\ndescription: ${description}\n---\n\n${instructions}\n`;
+}
+
+/** @param {string} yamlContent */
+export function renderClaudeAgent(yamlContent) {
+  return renderCursorAgent(yamlContent);
+}
+
+/** @param {string} yamlContent @param {string} [tomlTemplate] */
+export function renderCodexAgent(yamlContent, tomlTemplate) {
+  const { name, description, instructions } = parseAgentYaml(yamlContent);
+  if (tomlTemplate) {
+    return tomlTemplate
+      .replace(/\{\{name\}\}/g, name)
+      .replace(/\{\{description\}\}/g, description)
+      .replace(/\{\{instructions\}\}/g, instructions.replace(/\\/g, '\\\\').replace(/"/g, '\\"'));
+  }
+  const escapedInstructions = instructions.replace(/\\/g, '\\\\').replace(/"""/g, '\\"""');
+  return `name = "${name}"\ndescription = "${description}"\n\n[instructions]\ndeveloper_instructions = """\n${escapedInstructions}\n"""\n`;
+}
+
+/** @param {string} yamlPath */
+export function getAgentInstructionsFromFile(yamlPath) {
+  return parseAgentYaml(readFileSync(yamlPath, 'utf-8')).instructions;
+}
+
+/** @param {string} role e.g. specline-backend-dev */
+export function getAgentInstructions(role, packageRoot = PACKAGE_ROOT) {
+  const yamlPath = join(packageRoot, 'core', 'agents', `${role}.yaml`);
+  return getAgentInstructionsFromFile(yamlPath);
+}

package/lib/render.mjs

@@ -0,0 +1,126 @@
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { PACKAGE_ROOT, adapterDir } from './paths.mjs';
+import { parseAgentYaml } from './render-agents.mjs';
+
+const DEFAULT_VARS = {
+  cursor: {
+    DISPATCH: '使用 Task 工具，subagent_type="{{ROLE}}"',
+    CONFIRM: '使用 AskUserQuestion 工具',
+    LINT: '使用 ReadLints 工具',
+  },
+  claude: {
+    DISPATCH: '使用 dispatch_agent 工具，agent_name="{{ROLE}}"',
+    CONFIRM: '直接向用户提问',
+    LINT: '运行 bash lint 命令检查',
+  },
+  codex: {
+    DISPATCH: '使用 dispatch_agent 工具，agent_name="{{ROLE}}"',
+    CONFIRM: '直接向用户提问',
+    LINT: '运行 bash lint 命令检查',
+  },
+  opencode: {
+    DISPATCH: '使用 subagent 工具调度子 Agent',
+    CONFIRM: '直接向用户提问',
+    LINT: '运行 bash lint 命令检查',
+  },
+};
+
+/**
+ * Load vars from adapter deploy.json, fallback to DEFAULT_VARS.
+ * @param {string} platform
+ * @returns {{ DISPATCH: string, CONFIRM: string, LINT: string }}
+ */
+export function loadPlatformVars(platform) {
+  const deployPath = join(adapterDir(platform), 'deploy.json');
+  if (existsSync(deployPath)) {
+    try {
+      const manifest = JSON.parse(readFileSync(deployPath, 'utf-8'));
+      if (manifest.vars) return manifest.vars;
+    } catch { /* fallback */ }
+  }
+  return DEFAULT_VARS[platform] || DEFAULT_VARS.cursor;
+}
+
+/**
+ * Replace {{DISPATCH}}, {{CONFIRM}}, {{LINT}} template variables.
+ * Unknown {{...}} (including {{ROLE}}) are preserved as-is.
+ * @param {string} content - skill source content
+ * @param {{ DISPATCH?: string, CONFIRM?: string, LINT?: string }} vars
+ * @returns {string}
+ */
+export function renderSkill(content, vars) {
+  let result = content;
+  if (vars.DISPATCH != null) result = result.replace(/\{\{DISPATCH\}\}/g, vars.DISPATCH);
+  if (vars.CONFIRM != null) result = result.replace(/\{\{CONFIRM\}\}/g, vars.CONFIRM);
+  if (vars.LINT != null) result = result.replace(/\{\{LINT\}\}/g, vars.LINT);
+  return result;
+}
+
+/**
+ * Strip platform-conditional sections.
+ * Keeps sections matching targetPlatform, removes others.
+ *
+ * Format:
+ *   <!-- platform:cursor -->
+ *   ... cursor-specific content ...
+ *   <!-- /platform:cursor -->
+ *
+ *   <!-- platform:claude,codex,opencode -->
+ *   ... non-cursor content ...
+ *   <!-- /platform:claude,codex,opencode -->
+ *
+ * @param {string} content
+ * @param {string} targetPlatform
+ * @returns {string}
+ */
+export function stripPlatformSections(content, targetPlatform) {
+  return content.replace(
+    /<!-- platform:([\w,]+) -->\n([\s\S]*?)<!-- \/platform:\1 -->\n?/g,
+    (match, platforms, body) => {
+      const platformList = platforms.split(',').map((p) => p.trim());
+      if (platformList.includes(targetPlatform)) {
+        return body;
+      }
+      return '';
+    }
+  );
+}
+
+/**
+ * Full skill rendering pipeline: variable replacement + platform section stripping.
+ * @param {string} content
+ * @param {string} platform
+ * @returns {string}
+ */
+export function renderSkillForPlatform(content, platform) {
+  const vars = loadPlatformVars(platform);
+  let result = renderSkill(content, vars);
+  result = stripPlatformSections(result, platform);
+  return result;
+}
+
+/**
+ * Render agent YAML canonical to platform-specific format.
+ * @param {string} yamlContent - raw YAML from core/agents/*.yaml
+ * @param {string} platform
+ * @returns {string|null} rendered content, or null if platform doesn't render agents
+ */
+export function renderAgent(yamlContent, platform) {
+  if (platform === 'opencode') return null;
+
+  const { name, description, instructions } = parseAgentYaml(yamlContent);
+
+  if (platform === 'cursor' || platform === 'claude') {
+    return `---\nname: ${name}\ndescription: ${description}\n---\n\n${instructions}\n`;
+  }
+
+  if (platform === 'codex') {
+    const escapedName = (name || '').replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+    const escapedDesc = (description || '').replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+    const escapedInstructions = instructions.replace(/\\/g, '\\\\').replace(/"""/g, '\\"""');
+    return `name = "${escapedName}"\ndescription = "${escapedDesc}"\n\n[instructions]\ndeveloper_instructions = """\n${escapedInstructions}\n"""\n`;
+  }
+
+  return null;
+}

package/lib/sync.mjs

@@ -0,0 +1,253 @@
+import {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  unlinkSync,
+  mkdirSync,
+} from 'fs';
+import { join, dirname } from 'path';
+import { computeFileHash, sha256 } from './hash.mjs';
+import { readLockFile, writeLockFile, isV1Lock, migrateV1ToV2 } from './lock.mjs';
+import {
+  getCombinedUpstreamManifest,
+  writeManifestToProject,
+  readProjectPlatforms,
+  filterManifestByPlatforms,
+  hashManifestEntry,
+  readUpstreamContent,
+} from './deploy.mjs';
+import { PACKAGE_ROOT } from './paths.mjs';
+import { mergeHooksJson, mergeConfigYaml, backupBeforeOverwrite, mergeClaudeSettings } from './merge.mjs';
+
+const PROTECTED_PREFIXES = [
+  'specline/changes/',
+  'specline/specs/',
+  'specline/.pipeline-sessions.json',
+];
+
+const LEGACY_HOOK_SCRIPTS = [
+  '.cursor/hooks/specline-phase-guard.sh',
+  '.cursor/hooks/specline-agent-guard.sh',
+  '.cursor/hooks/specline-reminder.sh',
+  '.cursor/hooks/specline-auto-format.sh',
+];
+
+/** @param {string} relPath */
+function isProtectedPath(relPath) {
+  return PROTECTED_PREFIXES.some((prefix) => relPath === prefix || relPath.startsWith(prefix));
+}
+
+/** @param {string} relPath */
+function isHooksJson(relPath) {
+  return relPath === '.cursor/hooks.json' || relPath === '.codex/hooks.json';
+}
+
+/** @param {string} relPath */
+function isClaudeSettings(relPath) {
+  return relPath === '.claude/settings.json';
+}
+
+/** @param {string} relPath */
+function isConfigYaml(relPath) {
+  return relPath === 'specline/config.yaml';
+}
+
+/**
+ * Three-way hash comparison to classify sync action.
+ * @param {{ upstreamHash: string|null, lockHash: string|null, localHash: string|null, localExists: boolean }} info
+ * @returns {'NEW'|'WILL_UPDATE'|'UNCHANGED'|'MODIFIED_ONLY'|'CONFLICT'|'UPSTREAM_REMOVED'}
+ */
+function classifyFile({ upstreamHash, lockHash, localHash, localExists }) {
+  if (!upstreamHash && lockHash) return 'UPSTREAM_REMOVED';
+  if (!upstreamHash) return 'UNCHANGED';
+  if (!localExists) return 'NEW';
+
+  if (!lockHash) {
+    return localHash === upstreamHash ? 'UNCHANGED' : 'CONFLICT';
+  }
+
+  if (localHash === lockHash) {
+    return upstreamHash === lockHash ? 'UNCHANGED' : 'WILL_UPDATE';
+  }
+
+  return upstreamHash === lockHash ? 'MODIFIED_ONLY' : 'CONFLICT';
+}
+
+/** Read package version from package.json */
+function getPackageVersion(packageRoot) {
+  try {
+    return JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf-8')).version || '2.0.0';
+  } catch {
+    return '2.0.0';
+  }
+}
+
+/**
+ * @typedef {Object} SyncPlan
+ * @property {string} path
+ * @property {'NEW'|'WILL_UPDATE'|'UNCHANGED'|'MODIFIED_ONLY'|'CONFLICT'|'UPSTREAM_REMOVED'} type
+ */
+
+/**
+ * @typedef {Object} SyncResult
+ * @property {SyncPlan[]} plan
+ * @property {{ newCount: number, updated: number, conflicted: number, skippedModified: number, unchanged: number, upstreamRemoved: number }} stats
+ * @property {boolean} migrated
+ */
+
+/**
+ * Main sync logic for multi-platform projects.
+ *
+ * @param {string} projectDir
+ * @param {{ platforms?: string[], dryRun?: boolean, packageRoot?: string }} [options]
+ * @returns {SyncResult}
+ */
+export function runSync(projectDir, options = {}) {
+  const { dryRun = false, packageRoot = PACKAGE_ROOT } = options;
+
+  const lockData = readLockFile(projectDir);
+  if (!lockData) {
+    throw new Error('No lock file found. Run `specline init` first.');
+  }
+
+  const migrated = isV1Lock(lockData);
+  if (migrated) {
+    const inferredPlatforms = readProjectPlatforms(projectDir);
+    migrateV1ToV2(lockData, lockData.version || '2.0.0', inferredPlatforms);
+  }
+
+  let syncPlatforms;
+  if (options.platforms?.length) {
+    syncPlatforms = options.platforms;
+  } else if (lockData.platforms?.length) {
+    syncPlatforms = lockData.platforms;
+  } else {
+    syncPlatforms = readProjectPlatforms(projectDir);
+  }
+
+  const manifest = getCombinedUpstreamManifest(syncPlatforms, packageRoot);
+
+  const allPaths = new Set();
+  for (const p of manifest.keys()) allPaths.add(p);
+  for (const p of lockData.files.keys()) {
+    if (!isProtectedPath(p)) allPaths.add(p);
+  }
+  for (const legacy of LEGACY_HOOK_SCRIPTS) {
+    if (lockData.files.has(legacy) || existsSync(join(projectDir, legacy))) {
+      allPaths.add(legacy);
+    }
+  }
+
+  /** @type {SyncPlan[]} */
+  const plan = [];
+
+  for (const relPath of allPaths) {
+    if (isProtectedPath(relPath)) continue;
+
+    const entry = manifest.get(relPath);
+    const upstreamHash = entry ? hashManifestEntry(entry) : null;
+    const lockHash = lockData.files.get(relPath) || null;
+    const localPath = join(projectDir, relPath);
+    const localExists = existsSync(localPath);
+    const localHash = localExists ? computeFileHash(localPath) : null;
+
+    const type = classifyFile({ upstreamHash, lockHash, localHash, localExists });
+    plan.push({ path: relPath, type });
+  }
+
+  const stats = { newCount: 0, updated: 0, conflicted: 0, skippedModified: 0, unchanged: 0, upstreamRemoved: 0 };
+  for (const item of plan) {
+    switch (item.type) {
+      case 'NEW': stats.newCount++; break;
+      case 'WILL_UPDATE': stats.updated++; break;
+      case 'CONFLICT': stats.conflicted++; break;
+      case 'MODIFIED_ONLY': stats.skippedModified++; break;
+      case 'UNCHANGED': stats.unchanged++; break;
+      case 'UPSTREAM_REMOVED': stats.upstreamRemoved++; break;
+    }
+  }
+
+  if (dryRun) {
+    return { plan, stats, migrated };
+  }
+
+  const newFiles = new Map();
+
+  for (const item of plan) {
+    const destPath = join(projectDir, item.path);
+
+    switch (item.type) {
+      case 'UNCHANGED':
+      case 'MODIFIED_ONLY': {
+        if (existsSync(destPath)) {
+          newFiles.set(item.path, computeFileHash(destPath));
+        }
+        break;
+      }
+
+      case 'UPSTREAM_REMOVED': {
+        if (existsSync(destPath)) {
+          try { unlinkSync(destPath); } catch { /* ignore */ }
+        }
+        break;
+      }
+
+      case 'NEW':
+      case 'WILL_UPDATE':
+      case 'CONFLICT': {
+        const entry = manifest.get(item.path);
+        if (!entry) break;
+
+        const destDir = dirname(destPath);
+        if (!existsSync(destDir)) mkdirSync(destDir, { recursive: true });
+
+        if (isClaudeSettings(item.path)) {
+          const existingContent = existsSync(destPath) ? readFileSync(destPath, 'utf-8') : '{}';
+          const upstreamContent = readUpstreamContent(item.path, manifest);
+          if (upstreamContent) {
+            const merged = mergeClaudeSettings(existingContent, upstreamContent);
+            writeFileSync(destPath, merged, 'utf-8');
+            newFiles.set(item.path, sha256(merged));
+          }
+        } else if (isHooksJson(item.path)) {
+          const existingContent = existsSync(destPath) ? readFileSync(destPath, 'utf-8') : '{}';
+          const upstreamContent = readUpstreamContent(item.path, manifest);
+          if (upstreamContent) {
+            const merged = mergeHooksJson(existingContent, upstreamContent);
+            writeFileSync(destPath, merged, 'utf-8');
+            newFiles.set(item.path, sha256(merged));
+          }
+        } else if (isConfigYaml(item.path)) {
+          const existingContent = existsSync(destPath) ? readFileSync(destPath, 'utf-8') : '';
+          const upstreamContent = readUpstreamContent(item.path, manifest);
+          if (upstreamContent) {
+            const merged = mergeConfigYaml(existingContent, upstreamContent);
+            writeFileSync(destPath, merged, 'utf-8');
+            newFiles.set(item.path, sha256(merged));
+          }
+        } else {
+          if (item.type === 'CONFLICT' && existsSync(destPath)) {
+            backupBeforeOverwrite(destPath);
+          }
+          const subManifest = new Map([[item.path, entry]]);
+          writeManifestToProject(projectDir, subManifest);
+          newFiles.set(item.path, computeFileHash(destPath));
+        }
+        break;
+      }
+    }
+  }
+
+  const version = getPackageVersion(packageRoot);
+  writeLockFile(projectDir, {
+    version,
+    synced_at: new Date().toISOString(),
+    schema: 2,
+    platforms: [...syncPlatforms],
+    files: newFiles,
+  });
+
+  return { plan, stats, migrated };
+}
+
+

package/lib/tty-select.mjs

@@ -0,0 +1,89 @@
+import { PLATFORMS } from './paths.mjs';
+
+const PLATFORM_LABELS = {
+  cursor: 'Cursor',
+  claude: 'Claude Code',
+  codex: 'Codex',
+  opencode: 'OpenCode',
+};
+
+/**
+ * Interactive multi-select for platforms using raw mode ANSI escape.
+ * Falls back to ['cursor'] in non-TTY environments.
+ * @returns {Promise<string[]>}
+ */
+export async function selectPlatforms() {
+  if (!process.stdin.isTTY) return ['cursor'];
+
+  const items = PLATFORMS.map((name, i) => ({
+    name,
+    label: PLATFORM_LABELS[name] || name,
+    selected: i === 0,
+  }));
+
+  let cursor = 0;
+
+  const render = () => {
+    const lines = items.map((item, i) => {
+      const icon = item.selected ? '\x1b[36m◉\x1b[0m' : '◯';
+      const pointer = i === cursor ? '\x1b[1m>\x1b[0m ' : '  ';
+      return `${pointer}${icon} ${item.label}`;
+    });
+    return lines.join('\n');
+  };
+
+  const clearLines = (count) => {
+    for (let i = 0; i < count; i++) {
+      process.stdout.write('\x1b[1A\x1b[2K');
+    }
+  };
+
+  return new Promise((resolve) => {
+    process.stdout.write('选择目标平台（空格切换，回车确认）:\n');
+    process.stdout.write(render() + '\n');
+
+    const stdin = process.stdin;
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdin.setEncoding('utf-8');
+
+    const onData = (key) => {
+      if (key === '\u0003') {
+        // Ctrl+C
+        stdin.setRawMode(false);
+        stdin.removeListener('data', onData);
+        stdin.pause();
+        process.stdout.write('\n');
+        process.exit(130);
+      }
+
+      if (key === '\r' || key === '\n') {
+        stdin.setRawMode(false);
+        stdin.removeListener('data', onData);
+        stdin.pause();
+        process.stdout.write('\n');
+        const selected = items.filter((it) => it.selected).map((it) => it.name);
+        resolve(selected.length > 0 ? selected : ['cursor']);
+        return;
+      }
+
+      if (key === ' ') {
+        items[cursor].selected = !items[cursor].selected;
+      } else if (key === '\x1b[A' || key === 'k') {
+        cursor = (cursor - 1 + items.length) % items.length;
+      } else if (key === '\x1b[B' || key === 'j') {
+        cursor = (cursor + 1) % items.length;
+      } else if (key === 'a') {
+        const allSelected = items.every((it) => it.selected);
+        items.forEach((it) => { it.selected = !allSelected; });
+      } else {
+        return;
+      }
+
+      clearLines(items.length);
+      process.stdout.write(render() + '\n');
+    };
+
+    stdin.on('data', onData);
+  });
+}

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "specline",
-  "version": "1.4.0",
+  "version": "2.0.1",
   "description": "Spec-driven AI coding pipeline with deterministic quality gates for Cursor IDE",
   "bin": {
     "specline": "./cli.mjs"
   },
   "files": [
     "cli.mjs",
+    "lib/",
+    "core/",
+    "adapters/",
     "templates/"
   ],
   "keywords": [

package/templates/.cursor/README.md

@@ -0,0 +1,18 @@
+# ⚠️ DEPRECATED
+
+This directory is a legacy compatibility layer. **Do not edit files here directly.**
+
+## Source of Truth
+
+- Skills: `core/skills/`
+- Agents: `core/agents/`
+- Gates: `core/gates/`
+- Hooks: `core/hooks/`
+- Adapters: `adapters/{cursor,claude,codex,opencode}/`
+
+## Migration
+
+Files in this directory are no longer the primary source. They will be maintained
+for backward compatibility during the v1→v2 transition period.
+
+Use `specline sync` to update your project from the new `core/` + `adapters/` structure.