dream-wf 0.1.0

package/src/deps/index.js

@@ -0,0 +1,96 @@
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { pathExists, readTextIfExists } from '../lib/files.js';
+import { commandExists } from '../lib/trellis.js';
+
+export async function checkDependencies(rootDir, platform) {
+  const checks = [];
+
+  checks.push(binaryCheck('node', 'Node.js >= 18 is required.'));
+  checks.push(binaryCheck('python3', 'Python >= 3.9 is required by Trellis.'));
+  checks.push(binaryCheck('trellis', 'Install with: npm install -g @mindfoldhq/trellis@latest'));
+  checks.push(binaryCheck('uvx', 'Required for grok-search-mcp. Install uv: https://docs.astral.sh/uv/'));
+
+  checks.push(await fileCheck(path.join(rootDir, '.trellis'), 'Trellis project directory'));
+  checks.push(await fileCheck(path.join(rootDir, '.trellis', 'workflow.md'), 'Trellis workflow'));
+
+  if (platform === 'cursor') {
+    checks.push(await fileCheck(path.join(rootDir, '.cursor', 'rules', 'dream-wf.mdc'), 'Cursor dream-wf always-on rule'));
+    checks.push(await fileCheck(path.join(rootDir, '.cursor', 'skills', 'dream-wf-grill-prd', 'SKILL.md'), 'Cursor dream-wf grill PRD skill'));
+    checks.push(await fileCheck(path.join(rootDir, '.cursor', 'skills', 'dream-wf-mcp-policy', 'SKILL.md'), 'Cursor dream-wf MCP policy skill'));
+  }
+
+  if (platform === 'claude') {
+    checks.push(await contentCheck(path.join(rootDir, 'CLAUDE.md'), '<!-- DREAM-WF:START -->', 'Claude Code dream-wf entry block'));
+    checks.push(await fileCheck(path.join(rootDir, '.claude', 'skills', 'dream-wf-grill-prd', 'SKILL.md'), 'Claude Code dream-wf grill PRD skill'));
+    checks.push(await fileCheck(path.join(rootDir, '.claude', 'skills', 'dream-wf-mcp-policy', 'SKILL.md'), 'Claude Code dream-wf MCP policy skill'));
+  }
+
+  if (platform === 'opencode') {
+    checks.push(await contentCheck(path.join(rootDir, 'AGENTS.md'), '<!-- DREAM-WF:START -->', 'OpenCode dream-wf entry block'));
+    checks.push(await fileCheck(path.join(rootDir, '.opencode', 'skills', 'dream-wf-grill-prd', 'SKILL.md'), 'OpenCode dream-wf grill PRD skill'));
+    checks.push(await fileCheck(path.join(rootDir, '.opencode', 'skills', 'dream-wf-mcp-policy', 'SKILL.md'), 'OpenCode dream-wf MCP policy skill'));
+  }
+
+  checks.push(await secretScan(rootDir));
+
+  return checks;
+}
+
+function binaryCheck(command, hint) {
+  return {
+    name: command,
+    ok: commandExists(command),
+    hint
+  };
+}
+
+async function fileCheck(filePath, label) {
+  return {
+    name: label,
+    ok: await pathExists(filePath),
+    hint: `Missing ${filePath}`
+  };
+}
+
+async function contentCheck(filePath, needle, label) {
+  const text = await readTextIfExists(filePath);
+  return {
+    name: label,
+    ok: Boolean(text?.includes(needle)),
+    hint: `Missing ${needle} in ${filePath}`
+  };
+}
+
+async function secretScan(rootDir) {
+  const boardPath = path.join(rootDir, 'board.md');
+  const text = await readTextIfExists(boardPath);
+  if (!text) {
+    return { name: 'secret scan', ok: true, hint: 'No obvious project secret sample file found.' };
+  }
+
+  const suspicious = [
+    /GROK_API_KEY\s*[:=]/,
+    /TAVILY_API_KEY\s*[:=]/,
+    /WINDSURF_API_KEY\s*[:=]/,
+    /devin-session-/,
+    /tvly-[A-Za-z0-9_-]+/
+  ];
+
+  const hasSuspiciousContent = suspicious.some((pattern) => pattern.test(text));
+  return {
+    name: 'secret scan',
+    ok: !hasSuspiciousContent,
+    hint: hasSuspiciousContent ? 'Potential MCP secrets found in board.md. Do not commit real API keys.' : 'No obvious MCP secrets detected.'
+  };
+}
+
+export function installTrellisIfRequested() {
+  const result = spawnSync('npm', ['install', '-g', '@mindfoldhq/trellis@latest'], {
+    stdio: 'inherit'
+  });
+
+  if (result.status !== 0) {
+    throw new Error(`Failed to install Trellis with npm, exit code ${result.status ?? 'unknown'}.`);
+  }
+}

package/src/doctor/index.js

@@ -0,0 +1,16 @@
+import { checkDependencies } from '../deps/index.js';
+
+export async function runDoctor(rootDir, platform) {
+  const checks = await checkDependencies(rootDir, platform);
+  const ok = checks.every((check) => check.ok);
+  return { ok, checks };
+}
+
+export function formatDoctorReport(report) {
+  const lines = [];
+  lines.push(`dream-wf doctor: ${report.ok ? 'ok' : 'issues found'}`);
+  for (const check of report.checks) {
+    lines.push(`${check.ok ? '✓' : '✗'} ${check.name}${check.ok ? '' : ` — ${check.hint}`}`);
+  }
+  return lines.join('\n');
+}

package/src/lib/files.js

@@ -0,0 +1,64 @@
+import { mkdir, readFile, writeFile, access, copyFile } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import path from 'node:path';
+
+export async function pathExists(filePath) {
+  try {
+    await access(filePath, constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function readTextIfExists(filePath) {
+  if (!(await pathExists(filePath))) {
+    return undefined;
+  }
+  return readFile(filePath, 'utf8');
+}
+
+export async function writeTextFile(filePath, contents) {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await writeFile(filePath, contents, 'utf8');
+}
+
+export async function writeIfChanged(filePath, contents) {
+  const current = await readTextIfExists(filePath);
+  if (current === contents) {
+    return { changed: false, action: 'unchanged', path: filePath };
+  }
+
+  await writeTextFile(filePath, contents);
+  return { changed: true, action: current === undefined ? 'created' : 'updated', path: filePath };
+}
+
+export async function backupIfExists(filePath) {
+  if (!(await pathExists(filePath))) {
+    return undefined;
+  }
+
+  const backupPath = `${filePath}.bak.${new Date().toISOString().replace(/[:.]/g, '-')}`;
+  await copyFile(filePath, backupPath);
+  return backupPath;
+}
+
+export async function appendBlockOnce(filePath, marker, block, options = {}) {
+  const existing = await readTextIfExists(filePath);
+  if (existing?.includes(marker)) {
+    return { changed: false, action: 'unchanged', path: filePath };
+  }
+
+  const prefix = existing ? ensureTrailingNewline(existing) : '';
+  const next = `${prefix}${options.heading ? `\n${options.heading}\n` : '\n'}${block.trim()}\n`;
+  await writeTextFile(filePath, next);
+  return { changed: true, action: existing === undefined ? 'created' : 'updated', path: filePath };
+}
+
+export function ensureTrailingNewline(value) {
+  return value.endsWith('\n') ? value : `${value}\n`;
+}
+
+export function formatRelative(rootDir, filePath) {
+  return path.relative(rootDir, filePath) || '.';
+}

package/src/lib/json.js

@@ -0,0 +1,44 @@
+import { readTextIfExists, writeTextFile } from './files.js';
+
+export async function readJsonObject(filePath, fallback = {}) {
+  const text = await readTextIfExists(filePath);
+  if (!text) {
+    return fallback;
+  }
+
+  try {
+    const parsed = JSON.parse(text);
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : fallback;
+  } catch (error) {
+    throw new Error(`Failed to parse JSON at ${filePath}: ${error.message}`);
+  }
+}
+
+export async function writeJsonObject(filePath, value) {
+  await writeTextFile(filePath, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+export function pushUniqueByCommand(items, candidate) {
+  const command = extractCommand(candidate);
+  if (command && items.some((item) => extractCommand(item) === command)) {
+    return false;
+  }
+  items.push(candidate);
+  return true;
+}
+
+function extractCommand(item) {
+  if (!item || typeof item !== 'object') {
+    return undefined;
+  }
+
+  if (typeof item.command === 'string') {
+    return item.command;
+  }
+
+  if (Array.isArray(item.hooks) && item.hooks.length > 0) {
+    return item.hooks.map((hook) => hook?.command).filter(Boolean).join('|');
+  }
+
+  return undefined;
+}

package/src/lib/platforms.js

@@ -0,0 +1,32 @@
+export const SUPPORTED_PLATFORMS = new Set(['cursor', 'claude', 'opencode']);
+
+export function normalizePlatform(value) {
+  if (!value) {
+    return undefined;
+  }
+
+  return value.trim().toLowerCase();
+}
+
+export function assertSupportedPlatform(platform) {
+  if (!platform) {
+    throw new Error('Missing required -p <cursor|claude|opencode>.');
+  }
+
+  if (!SUPPORTED_PLATFORMS.has(platform)) {
+    throw new Error(`Unsupported platform "${platform}". Use one of: cursor, claude, opencode.`);
+  }
+}
+
+export function trellisPlatformFlag(platform) {
+  if (platform === 'claude') {
+    return '--claude';
+  }
+  if (platform === 'cursor') {
+    return '--cursor';
+  }
+  if (platform === 'opencode') {
+    return '--opencode';
+  }
+  assertSupportedPlatform(platform);
+}

package/src/lib/trellis.js

@@ -0,0 +1,118 @@
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { appendBlockOnce, pathExists, readTextIfExists, writeTextFile } from './files.js';
+import { trellisPlatformFlag } from './platforms.js';
+
+const DREAM_WF_MARKER = '<!-- dream-wf:profile:v1 -->';
+
+export async function detectTrellis(rootDir) {
+  const trellisDir = path.join(rootDir, '.trellis');
+  const workflowPath = path.join(trellisDir, 'workflow.md');
+  const scriptsDir = path.join(trellisDir, 'scripts');
+
+  return {
+    trellisDir,
+    workflowPath,
+    exists: await pathExists(trellisDir),
+    hasWorkflow: await pathExists(workflowPath),
+    hasScripts: await pathExists(scriptsDir),
+    cli: commandExists('trellis')
+  };
+}
+
+export async function ensureTrellisInitialized(rootDir, options) {
+  const state = await detectTrellis(rootDir);
+  if (state.exists) {
+    return { ...state, initialized: true, initCommand: undefined };
+  }
+
+  const platformFlag = trellisPlatformFlag(options.platform);
+  const initCommand = `trellis init -u ${options.developer ?? '<your-name>'} ${platformFlag}`;
+
+  if (!options.installDeps) {
+    return { ...state, initialized: false, initCommand };
+  }
+
+  if (!options.developer) {
+    throw new Error('Pass --developer <name> when using --install-deps so dream-wf can run trellis init non-interactively.');
+  }
+
+  if (!state.cli) {
+    throw new Error('trellis is not installed. Install it with: npm install -g @mindfoldhq/trellis@latest');
+  }
+
+  const result = spawnSync('trellis', ['init', '-u', options.developer, platformFlag], {
+    cwd: rootDir,
+    stdio: 'inherit'
+  });
+
+  if (result.status !== 0) {
+    throw new Error(`trellis init failed with exit code ${result.status ?? 'unknown'}.`);
+  }
+
+  return { ...(await detectTrellis(rootDir)), initialized: true, initCommand };
+}
+
+export async function installTrellisProfile(rootDir) {
+  const workflowPath = path.join(rootDir, '.trellis', 'workflow.md');
+  const existing = await readTextIfExists(workflowPath);
+  if (!existing) {
+    return {
+      changed: false,
+      action: 'skipped',
+      path: workflowPath,
+      reason: '.trellis/workflow.md not found. Run trellis init first.'
+    };
+  }
+
+  return appendBlockOnce(workflowPath, DREAM_WF_MARKER, dreamWorkflowBlock());
+}
+
+export async function writeSpecPolicy(rootDir, name, contents) {
+  return writeTextFile(path.join(rootDir, '.trellis', 'spec', 'guides', name), contents);
+}
+
+export function commandExists(command) {
+  const result = spawnSync('sh', ['-c', 'command -v "$1" >/dev/null 2>&1', 'sh', command], {
+    stdio: 'ignore'
+  });
+  return result.status === 0;
+}
+
+function dreamWorkflowBlock() {
+  return [
+    DREAM_WF_MARKER,
+    '',
+    '## Dream WF Profile',
+    '',
+    'This repository uses `dream-wf` as a Trellis custom patch profile. Trellis remains the source of truth for task lifecycle, specs, workflow state, before-dev, check, update-spec, break-loop, sub-agent context injection, and finish-work.',
+    '',
+    '### Dream WF Planning Override',
+    '',
+    'When a request enters Trellis planning, keep the native Trellis task artifacts and lifecycle, but use the `dream-wf-grill-prd` skill as the PRD clarification method before implementation.',
+    '',
+    'Rules:',
+    '',
+    '- Keep Trellis task creation, `prd.md`, `design.md`, `implement.md`, `implement.jsonl`, and `check.jsonl`.',
+    '- Do not use Trellis brainstorm as an open-ended interview style when `dream-wf-grill-prd` is available.',
+    '- Do not start planning by writing a speculative initial PRD. First inspect available context, then ask the first grill-me question.',
+    '- Use grill-me behavior for requirement discovery: ask one question at a time, provide 2-3 options and a recommended answer, and inspect code/docs/config before asking the user.',
+    '- Update `prd.md` only after a user answer, confirmed existing fact, or explicit decision is available.',
+    '- Treat PRD confirmation as separate from task creation consent.',
+    '- Generate initial spec candidates from user answers, PRD decisions, and verified project/code facts; require user review before treating them as stable conventions.',
+    '- Continue using `trellis-before-dev`, `trellis-check`, `trellis-update-spec`, and `trellis-break-loop` without replacing them.',
+    '',
+    '### Dream WF MCP Tool Policy',
+    '',
+    'Before searching, classify the need:',
+    '',
+    '- Codebase semantic understanding: prefer `fast-context-mcp` / `fast_context_search`.',
+    '- Exact known symbols or files: use exact search or direct reads.',
+    '- External docs, live technical information, and web pages: prefer `grok-search-mcp` / `web_search` or `web_fetch`.',
+    '- If the preferred MCP is unavailable, state the fallback reason before using another tool.',
+    '',
+    'Read `.trellis/spec/guides/dream-wf-mcp-policy.md` and `.trellis/spec/guides/dream-wf-prd-policy.md` when planning or starting implementation.',
+    '',
+    '<!-- /dream-wf:profile:v1 -->'
+  ].join('\n');
+}

package/src/platforms/claude-code/index.js

@@ -0,0 +1,54 @@
+import path from 'node:path';
+import { readFile, chmod } from 'node:fs/promises';
+import { readJsonObject, writeJsonObject, pushUniqueByCommand } from '../../lib/json.js';
+import { writeIfChanged } from '../../lib/files.js';
+import { installCommonDreamWfFiles, installManagedBlock, installSkill } from '../shared.js';
+
+export async function installClaudeCode(packageRoot, targetRoot, options) {
+  const results = [];
+
+  results.push(await installManagedBlock(packageRoot, targetRoot, 'templates/rules/claude-code/dream-wf-block.md', 'CLAUDE.md', '<!-- DREAM-WF:START -->', '<!-- DREAM-WF:END -->'));
+  results.push(await installSkill(packageRoot, targetRoot, '.claude', 'dream-wf-grill-prd'));
+  results.push(await installSkill(packageRoot, targetRoot, '.claude', 'dream-wf-mcp-policy'));
+  results.push(...await installCommonDreamWfFiles(packageRoot, targetRoot));
+
+  if (options.mode === 'strict') {
+    results.push(await installClaudeHook(packageRoot, targetRoot));
+    results.push(await mergeClaudeSettings(targetRoot));
+  }
+
+  return results;
+}
+
+async function installClaudeHook(packageRoot, targetRoot) {
+  const sourcePath = path.join(packageRoot, 'templates', 'hooks', 'claude-code', 'dream-wf-guard.py');
+  const targetPath = path.join(targetRoot, '.claude', 'hooks', 'dream-wf-guard.py');
+  const contents = await readFile(sourcePath, 'utf8');
+  const result = await writeIfChanged(targetPath, contents);
+  await chmod(targetPath, 0o755);
+  return result;
+}
+
+async function mergeClaudeSettings(rootDir) {
+  const settingsPath = path.join(rootDir, '.claude', 'settings.json');
+  const settings = await readJsonObject(settingsPath, {});
+  settings.hooks = settings.hooks ?? {};
+  settings.hooks.PreToolUse = settings.hooks.PreToolUse ?? [];
+
+  const changed = pushUniqueByCommand(settings.hooks.PreToolUse, {
+    matcher: '*',
+    hooks: [
+      {
+        type: 'command',
+        command: 'python3 "$CLAUDE_PROJECT_DIR/.claude/hooks/dream-wf-guard.py"',
+        timeout: 10
+      }
+    ]
+  });
+
+  if (changed) {
+    await writeJsonObject(settingsPath, settings);
+  }
+
+  return { changed, action: changed ? 'updated' : 'unchanged', path: settingsPath };
+}

package/src/platforms/cursor/index.js

@@ -0,0 +1,50 @@
+import path from 'node:path';
+import { readFile, chmod } from 'node:fs/promises';
+import { readJsonObject, writeJsonObject, pushUniqueByCommand } from '../../lib/json.js';
+import { writeIfChanged } from '../../lib/files.js';
+import { installCommonDreamWfFiles, installRuleFile, installSkill } from '../shared.js';
+
+export async function installCursor(packageRoot, targetRoot, options) {
+  const results = [];
+
+  results.push(await installRuleFile(packageRoot, targetRoot, 'templates/rules/cursor/dream-wf.mdc', '.cursor/rules/dream-wf.mdc'));
+  results.push(await installSkill(packageRoot, targetRoot, '.cursor', 'dream-wf-grill-prd'));
+  results.push(await installSkill(packageRoot, targetRoot, '.cursor', 'dream-wf-mcp-policy'));
+  results.push(...await installCommonDreamWfFiles(packageRoot, targetRoot));
+
+  if (options.mode === 'strict') {
+    results.push(await installCursorHook(packageRoot, targetRoot));
+    results.push(await mergeCursorHooks(targetRoot));
+  }
+
+  return results;
+}
+
+async function installCursorHook(packageRoot, targetRoot) {
+  const sourcePath = path.join(packageRoot, 'templates', 'hooks', 'cursor', 'dream-wf-guard.py');
+  const targetPath = path.join(targetRoot, '.cursor', 'hooks', 'dream-wf-guard.py');
+  const contents = await readFile(sourcePath, 'utf8');
+  const result = await writeIfChanged(targetPath, contents);
+  await chmod(targetPath, 0o755);
+  return result;
+}
+
+async function mergeCursorHooks(rootDir) {
+  const hooksPath = path.join(rootDir, '.cursor', 'hooks.json');
+  const hooks = await readJsonObject(hooksPath, { version: 1, hooks: {} });
+  hooks.version = hooks.version ?? 1;
+  hooks.hooks = hooks.hooks ?? {};
+  hooks.hooks.preToolUse = hooks.hooks.preToolUse ?? [];
+
+  const changed = pushUniqueByCommand(hooks.hooks.preToolUse, {
+    command: '.cursor/hooks/dream-wf-guard.py',
+    failClosed: true,
+    timeout: 10
+  });
+
+  if (changed) {
+    await writeJsonObject(hooksPath, hooks);
+  }
+
+  return { changed, action: changed ? 'updated' : 'unchanged', path: hooksPath };
+}

package/src/platforms/opencode/index.js

@@ -0,0 +1,26 @@
+import path from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { writeIfChanged } from '../../lib/files.js';
+import { installCommonDreamWfFiles, installManagedBlock, installSkill } from '../shared.js';
+
+export async function installOpenCode(packageRoot, targetRoot, options) {
+  const results = [];
+
+  results.push(await installManagedBlock(packageRoot, targetRoot, 'templates/rules/opencode/dream-wf-block.md', 'AGENTS.md', '<!-- DREAM-WF:START -->', '<!-- DREAM-WF:END -->'));
+  results.push(await installSkill(packageRoot, targetRoot, '.opencode', 'dream-wf-grill-prd'));
+  results.push(await installSkill(packageRoot, targetRoot, '.opencode', 'dream-wf-mcp-policy'));
+  results.push(...await installCommonDreamWfFiles(packageRoot, targetRoot));
+
+  if (options.mode === 'strict') {
+    results.push(await installOpenCodePlugin(packageRoot, targetRoot));
+  }
+
+  return results;
+}
+
+async function installOpenCodePlugin(packageRoot, targetRoot) {
+  const sourcePath = path.join(packageRoot, 'templates', 'hooks', 'opencode', 'dream-wf-guard.js');
+  const targetPath = path.join(targetRoot, '.opencode', 'plugins', 'dream-wf-guard.js');
+  const contents = await readFile(sourcePath, 'utf8');
+  return writeIfChanged(targetPath, contents);
+}

package/src/platforms/shared.js

@@ -0,0 +1,58 @@
+import path from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { readTextIfExists, writeIfChanged, writeTextFile } from '../lib/files.js';
+
+export async function installSkill(packageRoot, targetRoot, platformDir, skillName) {
+  const sourcePath = path.join(packageRoot, 'templates', 'skills', skillName, 'SKILL.md');
+  const targetPath = path.join(targetRoot, platformDir, 'skills', skillName, 'SKILL.md');
+  const contents = await readFile(sourcePath, 'utf8');
+  return writeIfChanged(targetPath, contents);
+}
+
+export async function installSpecGuide(packageRoot, targetRoot, fileName) {
+  const sourcePath = path.join(packageRoot, 'templates', 'spec', 'guides', fileName);
+  const targetPath = path.join(targetRoot, '.trellis', 'spec', 'guides', fileName);
+  const contents = await readFile(sourcePath, 'utf8');
+  return writeIfChanged(targetPath, contents);
+}
+
+export async function installCommonDreamWfFiles(packageRoot, targetRoot) {
+  return [
+    await installSpecGuide(packageRoot, targetRoot, 'dream-wf-prd-policy.md'),
+    await installSpecGuide(packageRoot, targetRoot, 'dream-wf-mcp-policy.md')
+  ];
+}
+
+export async function installRuleFile(packageRoot, targetRoot, sourceRelativePath, targetRelativePath) {
+  const contents = await readFile(path.join(packageRoot, sourceRelativePath), 'utf8');
+  return writeIfChanged(path.join(targetRoot, targetRelativePath), contents);
+}
+
+export async function installManagedBlock(packageRoot, targetRoot, sourceRelativePath, targetRelativePath, startMarker, endMarker) {
+  const block = await readFile(path.join(packageRoot, sourceRelativePath), 'utf8');
+  const targetPath = path.join(targetRoot, targetRelativePath);
+  const existing = await readTextIfExists(targetPath);
+
+  if (!existing) {
+    await writeTextFile(targetPath, block);
+    return { changed: true, action: 'created', path: targetPath };
+  }
+
+  const start = existing.indexOf(startMarker);
+  const end = existing.indexOf(endMarker);
+  let next;
+
+  if (start !== -1 && end !== -1 && end > start) {
+    const afterEnd = end + endMarker.length;
+    next = `${existing.slice(0, start)}${block.trim()}${existing.slice(afterEnd)}`;
+  } else {
+    next = `${existing.trimEnd()}\n\n${block.trim()}\n`;
+  }
+
+  if (next === existing) {
+    return { changed: false, action: 'unchanged', path: targetPath };
+  }
+
+  await writeTextFile(targetPath, next);
+  return { changed: true, action: 'updated', path: targetPath };
+}