specline 1.4.0 → 2.0.1

package/lib/gate.mjs

@@ -0,0 +1,103 @@
+import { existsSync } from 'fs';
+import { join } from 'path';
+import { spawnSync } from 'child_process';
+import { PACKAGE_ROOT } from './paths.mjs';
+
+const GATE_PHASES = new Set([
+  'new', 'list', 'artifacts', 'spec', 'semantic', 'build', 'lint',
+  'test-unit', 'test-integration', 'test-e2e', 'detect-modules', 'bind', 'archive', 'status',
+]);
+
+/**
+ * @param {string} projectDir
+ */
+export function resolveGateScript(projectDir) {
+  const projectGate = join(projectDir, 'specline', 'bin', 'gate.sh');
+  if (existsSync(projectGate)) return projectGate;
+  const packaged = join(PACKAGE_ROOT, 'core', 'gates', 'pipeline-gate.sh');
+  const legacy = join(projectDir, '.cursor', 'hooks', 'specline-pipeline-gate.sh');
+  if (projectDir === PACKAGE_ROOT && existsSync(packaged)) return packaged;
+  if (existsSync(legacy)) return legacy;
+  return packaged;
+}
+
+/**
+ * @param {string} phase
+ * @param {{ change?: string, projectDir?: string, execute?: boolean, json?: boolean, extraArgs?: string[] }} opts
+ */
+export function runGate(phase, opts = {}) {
+  const projectDir = opts.projectDir || process.cwd();
+  const script = resolveGateScript(projectDir);
+  const args = [script, phase];
+  if (opts.change) args.push('--change', opts.change);
+  if (opts.execute) args.push('--execute');
+  if (opts.extraArgs?.length) args.push(...opts.extraArgs);
+
+  const result = spawnSync('bash', args, {
+    cwd: projectDir,
+    encoding: 'utf-8',
+    env: { ...process.env, SPECLINE_PROJECT_ROOT: projectDir },
+  });
+
+  if (opts.json && phase === 'list') {
+    try {
+      result.jsonOutput = JSON.parse((result.stdout || '').trim());
+    } catch {
+      result.jsonOutput = (result.stdout || '').trim().split('\n').filter(Boolean);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * CLI entry point for `specline gate <subcommand> [--change <name>] [--json]`
+ * @param {string[]} argv - remaining args after "gate"
+ * @param {string} [cwd]
+ * @returns {number} exit code
+ */
+export function cliGate(argv, cwd) {
+  const projectDir = cwd || process.cwd();
+  const subcommand = argv[0];
+
+  if (!subcommand || subcommand === '--help') {
+    const phases = [...GATE_PHASES].join(', ');
+    process.stdout.write(`Usage: specline gate <subcommand> [--change <name>] [--json]\n\nSubcommands: ${phases}\n`);
+    return subcommand ? 0 : 1;
+  }
+
+  if (!isGatePhase(subcommand)) {
+    process.stderr.write(`Unknown gate subcommand: ${subcommand}\nAvailable: ${[...GATE_PHASES].join(', ')}\n`);
+    return 1;
+  }
+
+  let change = null;
+  let json = false;
+  for (let i = 1; i < argv.length; i++) {
+    if (argv[i] === '--change' && argv[i + 1]) {
+      change = argv[++i];
+    } else if (argv[i] === '--json') {
+      json = true;
+    }
+  }
+
+  const result = runGate(subcommand, { change, projectDir, json });
+
+  if (json && subcommand === 'list') {
+    const output = result.jsonOutput
+      ? JSON.stringify(result.jsonOutput, null, 2)
+      : (result.stdout || '');
+    process.stdout.write(output + '\n');
+  } else {
+    if (result.stdout) process.stdout.write(result.stdout);
+    if (result.stderr) process.stderr.write(result.stderr);
+  }
+
+  return result.status ?? 1;
+}
+
+export function isGatePhase(phase) {
+  return GATE_PHASES.has(phase);
+}
+
+export { GATE_PHASES };

package/lib/hash.mjs

@@ -0,0 +1,13 @@
+import { createHash } from 'crypto';
+import { readFileSync } from 'fs';
+
+/** @param {string|Buffer} content */
+export function sha256(content) {
+  const hash = createHash('sha256').update(content).digest('hex');
+  return `sha256:${hash}`;
+}
+
+/** @param {string} filePath */
+export function computeFileHash(filePath) {
+  return sha256(readFileSync(filePath));
+}

package/lib/hook.mjs

@@ -0,0 +1,105 @@
+import { existsSync } from 'fs';
+import { join } from 'path';
+import { spawnSync } from 'child_process';
+import { PACKAGE_ROOT } from './paths.mjs';
+
+/**
+ * @param {string} projectDir
+ */
+export function resolveSessionStartScript(projectDir) {
+  const deployed = join(projectDir, '.cursor', 'hooks', 'specline-session-start.sh');
+  if (existsSync(deployed)) return deployed;
+  return join(PACKAGE_ROOT, 'core', 'hooks', 'session-start.sh');
+}
+
+/**
+ * @param {object} cursorJson parsed stdout from session-start.sh
+ * @param {string} platform
+ */
+export function formatHookOutput(cursorJson, platform) {
+  const ctx = cursorJson.additional_context;
+  if (platform === 'cursor' || platform === 'opencode') {
+    if (ctx) return JSON.stringify({ additional_context: ctx });
+    return JSON.stringify(cursorJson);
+  }
+  if (platform === 'claude' || platform === 'codex') {
+    const additionalContext = ctx || '';
+    return JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'SessionStart',
+        additionalContext,
+      },
+    });
+  }
+  return JSON.stringify(cursorJson);
+}
+
+/**
+ * @param {{ platform?: string, projectDir?: string, input?: string }} opts
+ */
+export function runSessionStartHook(opts = {}) {
+  const platform = opts.platform || 'cursor';
+  const projectDir = opts.projectDir || process.cwd();
+  const script = resolveSessionStartScript(projectDir);
+  const input = opts.input ?? JSON.stringify({ session_id: 'cli', is_background_agent: false });
+
+  const result = spawnSync('bash', [script], {
+    cwd: projectDir,
+    input,
+    encoding: 'utf-8',
+    env: { ...process.env, SPECLINE_PROJECT_ROOT: projectDir },
+  });
+
+  let parsed = {};
+  try {
+    parsed = JSON.parse((result.stdout || '').trim() || '{}');
+  } catch {
+    parsed = {};
+  }
+
+  const formatted = formatHookOutput(parsed, platform);
+  return { ...result, formatted, parsed };
+}
+
+/**
+ * CLI entry point for `specline hook session-start [--platform <p>]`
+ * @param {string[]} argv - remaining args after "hook session-start"
+ * @param {string} [cwd]
+ * @returns {number} exit code
+ */
+export function cliHookSessionStart(argv, cwd) {
+  const projectDir = cwd || process.cwd();
+  let platform = 'cursor';
+
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--platform' && argv[i + 1]) {
+      platform = argv[++i];
+    }
+  }
+
+  const { formatted, status } = runSessionStartHook({ platform, projectDir });
+  process.stdout.write(formatted + '\n');
+  return status ?? 0;
+}
+
+/**
+ * CLI entry point for `specline hook <subcommand> [opts]`
+ * @param {string[]} argv - remaining args after "hook"
+ * @param {string} [cwd]
+ * @returns {number} exit code
+ */
+export function cliHook(argv, cwd) {
+  const subcommand = argv[0];
+
+  if (!subcommand || subcommand === '--help') {
+    process.stdout.write('Usage: specline hook <subcommand> [options]\n\nSubcommands: session-start\n');
+    return subcommand ? 0 : 1;
+  }
+
+  if (subcommand === 'session-start') {
+    return cliHookSessionStart(argv.slice(1), cwd);
+  }
+
+  process.stderr.write(`Unknown hook subcommand: ${subcommand}\nAvailable: session-start\n`);
+  return 1;
+}

package/lib/init.mjs

@@ -0,0 +1,122 @@
+import { existsSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import {
+  deployPlatforms,
+  buildUpstreamLockData,
+  readPlatformsYaml,
+  writePlatformsYaml,
+  countDeployedFiles,
+  PLATFORMS,
+} from './deploy.mjs';
+import { writeLockFile } from './lock.mjs';
+import { PACKAGE_ROOT } from './paths.mjs';
+import { selectPlatforms } from './tty-select.mjs';
+
+/**
+ * @param {string} raw
+ * @returns {string[]}
+ */
+export function parsePlatformList(raw) {
+  if (!raw || raw === 'none') return [];
+  if (raw === 'all') return [...PLATFORMS];
+  return raw
+    .split(',')
+    .map((p) => p.trim().toLowerCase())
+    .filter((p) => PLATFORMS.includes(p));
+}
+
+/**
+ * @param {boolean} isTTY
+ * @param {string|undefined} platformArg
+ */
+export async function resolvePlatforms(isTTY, platformArg) {
+  if (platformArg !== undefined) {
+    return parsePlatformList(platformArg);
+  }
+  return selectPlatforms();
+}
+
+/**
+ * @param {object} opts
+ * @param {string} opts.target
+ * @param {string[]} opts.platforms
+ * @param {boolean} opts.withShellGuard
+ * @param {string} opts.version
+ * @param {boolean} [opts.force]
+ */
+export function runInit(opts) {
+  const { target, platforms, withShellGuard, version, force } = opts;
+
+  const speclineDir = join(target, 'specline');
+  const alreadyInitialized = existsSync(join(speclineDir, '.specline-lock.yaml'));
+
+  if (alreadyInitialized && !force && platforms.length > 0) {
+    return runAppendPlatforms({ target, platforms, withShellGuard, version });
+  }
+
+  if (platforms.length === 0) {
+    for (const dir of ['specline/changes/archive', 'specline/specs', 'specline/bin']) {
+      const full = join(target, dir);
+      if (!existsSync(full)) mkdirSync(full, { recursive: true });
+    }
+    writePlatformsYaml(target, []);
+
+    const lockData = buildUpstreamLockData(version, PACKAGE_ROOT, { platforms: [] });
+    writeLockFile(target, lockData);
+
+    return { skills: 0, agents: 0, hooks: 0, platforms: [], appended: [] };
+  }
+
+  deployPlatforms(target, platforms, PACKAGE_ROOT, { withShellGuard, platforms });
+  writePlatformsYaml(target, platforms);
+
+  const lockData = buildUpstreamLockData(version, PACKAGE_ROOT, {
+    withShellGuard,
+    platforms,
+  });
+  writeLockFile(target, lockData);
+
+  return { ...countDeployedFiles(target), platforms, appended: [] };
+}
+
+/**
+ * Append new platforms without resetting existing configuration.
+ * @param {object} opts
+ * @param {string} opts.target
+ * @param {string[]} opts.platforms - requested platforms
+ * @param {boolean} opts.withShellGuard
+ * @param {string} opts.version
+ */
+function runAppendPlatforms(opts) {
+  const { target, platforms: requested, withShellGuard, version } = opts;
+
+  const existingPlatforms = readPlatformsYaml(target) || [];
+  const newPlatforms = requested.filter((p) => !existingPlatforms.includes(p));
+
+  if (newPlatforms.length === 0) {
+    return {
+      skills: 0,
+      agents: 0,
+      hooks: 0,
+      platforms: existingPlatforms,
+      appended: [],
+    };
+  }
+
+  deployPlatforms(target, newPlatforms, PACKAGE_ROOT, { withShellGuard, platforms: newPlatforms });
+
+  const allPlatforms = [...existingPlatforms, ...newPlatforms];
+  writePlatformsYaml(target, allPlatforms);
+
+  const lockData = buildUpstreamLockData(version, PACKAGE_ROOT, {
+    withShellGuard,
+    platforms: allPlatforms,
+  });
+  writeLockFile(target, lockData);
+
+  return {
+    ...countDeployedFiles(target),
+    platforms: allPlatforms,
+    appended: newPlatforms,
+  };
+}

package/lib/lock.mjs

@@ -0,0 +1,99 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { computeFileHash, sha256 } from './hash.mjs';
+
+/**
+ * @typedef {Object} LockData
+ * @property {string} version
+ * @property {string} synced_at
+ * @property {number} [schema]
+ * @property {string[]} [platforms]
+ * @property {Map<string, string>} files
+ */
+
+/** @param {string} projectDir */
+export function lockFilePath(projectDir) {
+  return join(projectDir, 'specline', '.specline-lock.yaml');
+}
+
+/** @param {string} projectDir @returns {LockData|null} */
+export function readLockFile(projectDir) {
+  const lockPath = lockFilePath(projectDir);
+  if (!existsSync(lockPath)) return null;
+
+  const lines = readFileSync(lockPath, 'utf-8').split('\n');
+  /** @type {LockData} */
+  const result = { version: '', synced_at: '', files: new Map() };
+  let inFiles = false;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed === '' || trimmed.startsWith('#')) continue;
+
+    if (trimmed.startsWith('version:')) {
+      result.version = trimmed.slice('version:'.length).trim().replace(/^"(.*)"$/, '$1');
+    } else if (trimmed.startsWith('synced_at:')) {
+      result.synced_at = trimmed.slice('synced_at:'.length).trim().replace(/^"(.*)"$/, '$1');
+    } else if (trimmed.startsWith('schema:')) {
+      result.schema = Number(trimmed.slice('schema:'.length).trim());
+    } else if (trimmed.startsWith('platforms:')) {
+      const raw = trimmed.slice('platforms:'.length).trim();
+      if (raw.startsWith('[')) {
+        result.platforms = raw
+          .slice(1, -1)
+          .split(',')
+          .map((p) => p.trim().replace(/^"(.*)"$/, '$1'))
+          .filter(Boolean);
+      }
+    } else if (trimmed === 'files:') {
+      inFiles = true;
+    } else if (inFiles && trimmed.includes(':')) {
+      const colonIdx = trimmed.indexOf(':');
+      const key = trimmed.slice(0, colonIdx).trim();
+      const value = trimmed.slice(colonIdx + 1).trim();
+      result.files.set(key, value);
+    }
+  }
+
+  return result;
+}
+
+/** @param {string} projectDir @param {LockData} lockData */
+export function writeLockFile(projectDir, lockData) {
+  const lockDir = join(projectDir, 'specline');
+  if (!existsSync(lockDir)) {
+    mkdirSync(lockDir, { recursive: true });
+  }
+  const lockPath = lockFilePath(projectDir);
+  const lines = [
+    '# Specline Lock File — 自动生成，请勿手动编辑',
+    `version: "${lockData.version}"`,
+    `synced_at: "${lockData.synced_at}"`,
+  ];
+  if (lockData.schema != null) {
+    lines.push(`schema: ${lockData.schema}`);
+  }
+  if (lockData.platforms?.length) {
+    lines.push(`platforms: [${lockData.platforms.map((p) => `"${p}"`).join(', ')}]`);
+  }
+  lines.push('files:');
+  for (const [key, value] of lockData.files) {
+    lines.push(`  ${key}: ${value}`);
+  }
+  writeFileSync(lockPath, lines.join('\n') + '\n', 'utf-8');
+}
+
+/** @returns {boolean} */
+export function isV1Lock(lockData) {
+  return lockData != null && lockData.schema == null && !lockData.platforms?.length;
+}
+
+/** @param {LockData} lockData @param {string} packageVersion @param {string[]} [platforms] */
+export function migrateV1ToV2(lockData, packageVersion, platforms = ['cursor']) {
+  lockData.schema = 2;
+  lockData.version = packageVersion;
+  lockData.platforms = [...platforms];
+  return lockData;
+}
+
+export { computeFileHash, sha256 };

package/lib/merge.mjs

@@ -0,0 +1,188 @@
+import { copyFileSync } from 'fs';
+
+/**
+ * hooks.json 语义合并：清理 specline 官方条目，注入模板最新 hook
+ */
+export function mergeHooksJson(existingContent, templateContent, warn = () => {}) {
+  let existingObj;
+  let templateObj;
+  try {
+    existingObj = JSON.parse(existingContent);
+  } catch {
+    warn('hooks.json 解析失败，将使用模板完整替换');
+    return templateContent;
+  }
+  try {
+    templateObj = JSON.parse(templateContent);
+  } catch {
+    warn('模板 hooks.json 解析失败，保留现有文件');
+    return existingContent;
+  }
+
+  if (!existingObj.hooks) existingObj.hooks = {};
+
+  for (const eventName of Object.keys(existingObj.hooks)) {
+    existingObj.hooks[eventName] = existingObj.hooks[eventName].filter(
+      (entry) => !(entry.command || '').includes('specline-') && !(entry.command || '').includes('specline '),
+    );
+  }
+
+  for (const eventName of Object.keys(templateObj.hooks || {})) {
+    if (!existingObj.hooks[eventName]) existingObj.hooks[eventName] = [];
+    existingObj.hooks[eventName] = [
+      ...templateObj.hooks[eventName],
+      ...existingObj.hooks[eventName],
+    ];
+  }
+  return JSON.stringify(existingObj, null, 2) + '\n';
+}
+
+export function countCustomHooks(hooksObj) {
+  let count = 0;
+  for (const eventName of Object.keys(hooksObj.hooks || {})) {
+    for (const entry of hooksObj.hooks[eventName] || []) {
+      const cmd = entry.command || '';
+      if (!cmd.includes('specline')) count++;
+    }
+  }
+  return count;
+}
+
+/** Claude Code settings.json — merge hooks 段 */
+export function mergeClaudeSettings(existingContent, templateContent, warn = () => {}) {
+  let existingObj = {};
+  let templateObj;
+  try {
+    if (existingContent.trim()) existingObj = JSON.parse(existingContent);
+  } catch {
+    warn('settings.json 解析失败，将使用模板 hooks 段');
+    existingObj = {};
+  }
+  try {
+    templateObj = JSON.parse(templateContent);
+  } catch {
+    return existingContent;
+  }
+  const tmplHooks = templateObj.hooks || templateObj;
+  if (!existingObj.hooks) existingObj.hooks = {};
+  for (const [eventName, entries] of Object.entries(tmplHooks)) {
+    if (!existingObj.hooks[eventName]) existingObj.hooks[eventName] = [];
+    existingObj.hooks[eventName] = existingObj.hooks[eventName].filter(
+      (e) => !JSON.stringify(e).includes('specline'),
+    );
+    existingObj.hooks[eventName] = [...entries, ...existingObj.hooks[eventName]];
+  }
+  return JSON.stringify(existingObj, null, 2) + '\n';
+}
+
+/** opencode.json plugin 数组 merge */
+export function mergeOpencodeJson(existingContent, pluginPath = './specline/opencode-plugin') {
+  let base = {};
+  if (existingContent?.trim()) {
+    try {
+      base = JSON.parse(existingContent);
+    } catch {
+      base = {};
+    }
+  }
+  const key = base.plugin != null ? 'plugin' : 'plugins';
+  const current = Array.isArray(base[key]) ? base[key] : [];
+  const set = new Set(current);
+  set.add(pluginPath);
+  base[key] = [...set];
+  return JSON.stringify(base, null, 2) + '\n';
+}
+
+function parseYamlSections(content) {
+  const lines = content.split('\n');
+  const sections = [];
+  let currentComments = [];
+  let currentKey = null;
+  let currentBodyLines = [];
+  let inBody = false;
+
+  function flushSection() {
+    if (currentComments.length > 0 || currentBodyLines.length > 0 || currentKey) {
+      const bodyStr = currentBodyLines.join('\n');
+      const bodyTrimmed = bodyStr.trim();
+      const onlyKeyDeclaration = currentKey !== null &&
+        currentBodyLines.length === 1 &&
+        bodyTrimmed.match(/^\w[\w_-]*\s*:\s*$/) !== null;
+      const isEmpty = bodyTrimmed === '' || bodyTrimmed.startsWith('#') || onlyKeyDeclaration;
+      sections.push({ key: currentKey, headerComments: [...currentComments], body: bodyStr, isEmpty });
+    }
+    currentComments = [];
+    currentKey = null;
+    currentBodyLines = [];
+    inBody = false;
+  }
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed === '') {
+      if (inBody) currentBodyLines.push(line);
+      continue;
+    }
+    if (trimmed.startsWith('#')) {
+      if (inBody) currentBodyLines.push(line);
+      else currentComments.push(line);
+      continue;
+    }
+    const topKeyMatch = line.match(/^(\w[\w_-]*)\s*:(.*)/);
+    if (topKeyMatch && !line.startsWith(' ') && !line.startsWith('\t')) {
+      flushSection();
+      currentKey = topKeyMatch[1];
+      currentBodyLines = [line];
+      inBody = true;
+      continue;
+    }
+    if (inBody) currentBodyLines.push(line);
+  }
+  flushSection();
+  return sections;
+}
+
+function findSection(sections, key) {
+  return sections.find((s) => s.key === key) || null;
+}
+
+export function mergeConfigYaml(existingContent, templateContent) {
+  const existingSections = parseYamlSections(existingContent);
+  const templateSections = parseYamlSections(templateContent);
+  const resultLines = [];
+
+  for (const tmplSec of templateSections) {
+    const existSec = findSection(existingSections, tmplSec.key);
+    if (existSec) {
+      if (!existSec.isEmpty && existSec.body.trim() !== tmplSec.body.trim()) {
+        resultLines.push(...tmplSec.headerComments);
+        resultLines.push(existSec.body);
+      } else {
+        resultLines.push(...tmplSec.headerComments);
+        resultLines.push(tmplSec.body);
+      }
+      resultLines.push('');
+    } else if (tmplSec.key !== null) {
+      resultLines.push('# 🆕 新增配置段 (specline sync)');
+      resultLines.push(...tmplSec.headerComments);
+      resultLines.push(tmplSec.body);
+      resultLines.push('');
+    }
+  }
+
+  for (const existSec of existingSections) {
+    if (existSec.key === null) continue;
+    if (!findSection(templateSections, existSec.key)) {
+      resultLines.push(...existSec.headerComments);
+      resultLines.push(existSec.body);
+      resultLines.push('');
+    }
+  }
+  return resultLines.join('\n');
+}
+
+export function backupBeforeOverwrite(destPath) {
+  const backupPath = destPath + '.orig';
+  copyFileSync(destPath, backupPath);
+  return backupPath;
+}

package/lib/paths.mjs

@@ -0,0 +1,40 @@
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/** npm 包根目录 */
+export const PACKAGE_ROOT = join(__dirname, '..');
+
+export const CORE_DIR = join(PACKAGE_ROOT, 'core');
+export const ADAPTERS_DIR = join(PACKAGE_ROOT, 'adapters');
+export const TEMPLATES_DIR = join(PACKAGE_ROOT, 'templates');
+
+export const CORE_SKILLS = join(CORE_DIR, 'skills');
+export const CORE_AGENTS = join(CORE_DIR, 'agents');
+export const CORE_GATES = join(CORE_DIR, 'gates');
+export const CORE_HOOKS = join(CORE_DIR, 'hooks');
+export const CORE_BOOTSTRAP = join(CORE_DIR, 'bootstrap');
+export const CORE_TEMPLATES = join(CORE_DIR, 'templates');
+
+/** @param {string} platform */
+export function adapterDir(platform) {
+  return join(ADAPTERS_DIR, platform);
+}
+
+/** @param {string} platform */
+export function deployManifestPath(platform) {
+  return join(adapterDir(platform), 'deploy.json');
+}
+
+/** @param {string} projectDir */
+export function projectSpeclineDir(projectDir) {
+  return join(projectDir, 'specline');
+}
+
+/** @param {string} projectDir */
+export function projectPlatformsPath(projectDir) {
+  return join(projectSpeclineDir(projectDir), 'platforms.yaml');
+}
+
+export const PLATFORMS = ['cursor', 'claude', 'codex', 'opencode'];