pluribus-context 0.2.0

package/src/commands/init.js

@@ -0,0 +1,153 @@
+/**
+ * pluribus init — create a pluribus.md file in the current directory.
+ * Supports --name, --description, --tools flags or interactive prompts.
+ */
+
+import * as fs from 'fs'
+import * as path from 'path'
+import * as readline from 'readline'
+import { SUPPORTED_TOOLS } from '../skills/built-in.js'
+
+const DEFAULT_TOOLS = ['claude', 'cursor', 'openclaw']
+
+/**
+ * Ask a question via readline and return the answer.
+ * @param {readline.Interface} rl
+ * @param {string} question
+ * @param {string} defaultValue
+ * @returns {Promise<string>}
+ */
+function ask(rl, question, defaultValue) {
+  return new Promise((resolve) => {
+    const prompt = defaultValue ? `${question} (${defaultValue}): ` : `${question}: `
+    rl.question(prompt, (answer) => {
+      resolve(answer.trim() || defaultValue || '')
+    })
+  })
+}
+
+/**
+ * @param {Record<string, string | boolean>} args
+ */
+export async function runInit(args) {
+  const targetDir = process.cwd()
+  const outputPath = path.join(targetDir, 'pluribus.md')
+
+  // Check if file already exists
+  if (fs.existsSync(outputPath)) {
+    console.log(`⚠️  pluribus.md already exists at ${outputPath}`)
+    console.log('   Delete it first or run \`pluribus sync\` to regenerate outputs.')
+    process.exit(1)
+  }
+
+  let name = args.name || ''
+  let description = args.description || ''
+  let toolsRaw = args.tools || ''
+
+  const isInteractive = !args.name && !args.description && process.stdin.isTTY
+
+  if (isInteractive) {
+    console.log('\n📝 Pluribus Init — let\'s set up your context file.\n')
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout })
+
+    name = await ask(rl, '  Your name or team name', path.basename(targetDir))
+    description = await ask(rl, '  Project description (one line)', 'A new project')
+    const toolsDefault = DEFAULT_TOOLS.join(',')
+    const toolsInput = await ask(rl, `  Tools to enable (${SUPPORTED_TOOLS.join(',')})`, toolsDefault)
+    toolsRaw = toolsInput
+
+    rl.close()
+    console.log('')
+  } else {
+    // Non-interactive: fill defaults
+    if (!name) name = path.basename(targetDir)
+    if (!description) description = 'A new project'
+    if (!toolsRaw) toolsRaw = DEFAULT_TOOLS.join(',')
+  }
+
+  const tools = String(toolsRaw)
+    .split(',')
+    .map((t) => t.trim().toLowerCase())
+    .filter((t) => t.length > 0)
+
+  const unknownTools = tools.filter((t) => !SUPPORTED_TOOLS.includes(t))
+  if (unknownTools.length > 0) {
+    console.warn(`⚠️  Unknown tools (will be ignored by sync): ${unknownTools.join(', ')}`)
+    console.warn(`   Supported: ${SUPPORTED_TOOLS.join(', ')}`)
+  }
+
+  const content = generatePluribusTemplate(name, description, tools)
+
+  fs.writeFileSync(outputPath, content, 'utf8')
+
+  console.log(`✅ pluribus.md created at ${outputPath}`)
+  console.log(`📝 Edit the file to fill in your project context.`)
+  console.log(`🔄 Run \`pluribus sync\` to generate tool-specific files.`)
+  console.log(`\n   Tools enabled: ${tools.join(', ')}`)
+}
+
+/**
+ * Generate the pluribus.md template content.
+ * @param {string} name
+ * @param {string} description
+ * @param {string[]} tools
+ * @returns {string}
+ */
+function generatePluribusTemplate(name, description, tools) {
+  const toolsComment = tools.length > 0
+    ? `<!-- pluribus:tools: ${tools.join(',')} -->`
+    : ''
+
+  return `${toolsComment}
+
+# Identity
+
+I am ${name}, building **${description}**.
+
+<!-- Describe who you are, what the project is, and (if applicable) the AI persona to adopt. Keep this concise — 3–10 lines. -->
+
+# Stack
+
+<!-- List your full technical picture: language + version, frameworks, key libraries, test tools, linter/formatter, infrastructure. -->
+<!-- Example:
+- **Language:** TypeScript 5.4 (strict mode)
+- **Runtime:** Node.js 22 LTS
+- **Framework:** None — pure Node CLI
+- **Testing:** Jest 29 + ts-jest
+- **Package manager:** pnpm
+-->
+
+- **Language:** (e.g. TypeScript 5.4)
+- **Runtime:** (e.g. Node.js 22 LTS)
+- **Framework:** (e.g. None)
+
+# Conventions
+
+<!-- How code is written in this project. Be opinionated and explicit. Cover: async patterns, error handling, naming conventions, file structure, forbidden patterns. -->
+<!-- Example:
+- Always use \`async/await\` — never \`.then()/.catch()\` chains
+- No class-based code — use plain functions and closures
+- File naming: \`kebab-case.ts\`
+-->
+
+- (Add your coding conventions here)
+
+# Goals
+
+<!-- What this project is optimizing for. List 3–7 goals in priority order. Be specific to this project. -->
+
+1. (First goal)
+2. (Second goal)
+3. (Third goal)
+
+# Constraints
+
+<!-- Hard rules. What the AI must never do, regardless of context. -->
+<!-- Example:
+- Never introduce new dependencies without explicit confirmation
+- Never use \`eval\`, \`Function()\`, or dynamic \`require()\`
+-->
+
+- (Add your hard constraints here)
+`.trimStart()
+}

package/src/commands/sync.js

@@ -0,0 +1,213 @@
+/**
+ * pluribus sync — read pluribus.md and generate tool-specific output files.
+ * Supports --dry-run, --tools, --source flags.
+ */
+
+import * as fs from 'fs'
+import * as path from 'path'
+import { parsePluribusFile, validateSections, REQUIRED_SECTIONS } from '../utils/parser.js'
+import { resolveImportsAsync } from '../utils/imports.js'
+import { renderTemplate, parseSkillFile } from '../utils/renderer.js'
+import { BUILT_IN_SKILLS, SUPPORTED_TOOLS } from '../skills/built-in.js'
+
+/**
+ * @param {Record<string, string | boolean>} args
+ */
+export async function runSync(args) {
+  const isDryRun = Boolean(args['dry-run'])
+  const sourceArg = typeof args.source === 'string' ? args.source : null
+  const toolsArg = typeof args.tools === 'string' ? args.tools : null
+  const updateImports = Boolean(args['update-imports'])
+
+  const cwd = process.cwd()
+
+  // Resolve source file
+  const sourcePath = sourceArg
+    ? path.resolve(cwd, sourceArg)
+    : path.join(cwd, 'pluribus.md')
+
+  if (!fs.existsSync(sourcePath)) {
+    console.error(`❌ pluribus.md not found at: ${sourcePath}`)
+    console.error(`   Run \`pluribus init\` to create one.`)
+    process.exit(1)
+  }
+
+  // Read and parse pluribus.md
+  let rawContent
+  try {
+    rawContent = fs.readFileSync(sourcePath, 'utf8')
+  } catch (err) {
+    console.error(`❌ Could not read ${sourcePath}: ${err.message}`)
+    process.exit(1)
+  }
+
+  let resolvedContent
+  try {
+    const projectDir = path.dirname(sourcePath)
+    const resolved = await resolveImportsAsync(sourcePath, {
+      rootDir: projectDir,
+      allowRemote: updateImports,
+      lockfilePath: path.join(projectDir, 'pluribus.lock.json'),
+      cacheDir: path.join(projectDir, '.pluribus', 'cache', 'remote'),
+      updateLockfile: updateImports,
+    })
+    resolvedContent = resolved.content
+  } catch (err) {
+    console.error(`❌ Could not resolve imports for ${sourcePath}: ${err.message}`)
+    process.exit(1)
+  }
+
+  const sections = parsePluribusFile(resolvedContent)
+
+  // Validate required sections
+  const { valid, errors } = validateSections(sections)
+  if (!valid) {
+    console.error('❌ pluribus.md has validation errors:')
+    for (const e of errors) {
+      console.error(`   • ${e}`)
+    }
+    console.error(`\n   Complete all required sections (${REQUIRED_SECTIONS.join(', ')}) and re-run.`)
+    process.exit(1)
+  }
+
+  // Determine which tools to sync
+  let toolsToSync
+
+  if (toolsArg) {
+    // Explicit override via --tools flag
+    toolsToSync = toolsArg
+      .split(',')
+      .map((t) => t.trim().toLowerCase())
+      .filter((t) => t.length > 0)
+  } else {
+    // Read from pluribus.md comment: <!-- pluribus:tools: claude,cursor,openclaw -->
+    const toolsCommentMatch = rawContent.match(/<!--\s*pluribus:tools:\s*([^-]+)\s*-->/)
+    if (toolsCommentMatch) {
+      toolsToSync = toolsCommentMatch[1]
+        .split(',')
+        .map((t) => t.trim().toLowerCase())
+        .filter((t) => t.length > 0)
+    } else {
+      // Default: all supported tools
+      toolsToSync = [...SUPPORTED_TOOLS]
+    }
+  }
+
+  const unknownTools = toolsToSync.filter((t) => !SUPPORTED_TOOLS.includes(t))
+  if (unknownTools.length > 0) {
+    console.warn(`⚠️  Unknown tools will be skipped: ${unknownTools.join(', ')}`)
+    console.warn(`   Supported: ${SUPPORTED_TOOLS.join(', ')}`)
+    toolsToSync = toolsToSync.filter((t) => SUPPORTED_TOOLS.includes(t))
+  }
+
+  if (toolsToSync.length === 0) {
+    console.error('❌ No valid tools to sync.')
+    process.exit(1)
+  }
+
+  console.log(`🔄 Syncing pluribus.md → ${toolsToSync.join(', ')}${isDryRun ? ' (dry run)' : ''}`)
+  console.log('')
+
+  let successCount = 0
+  let failCount = 0
+
+  for (const toolId of toolsToSync) {
+    // Check for local skill override first: pluribus/skills/<tool>.md
+    const localSkillPath = path.join(cwd, 'pluribus', 'skills', `${toolId}.md`)
+    let skill
+
+    if (fs.existsSync(localSkillPath)) {
+      console.log(`   📂 Using local skill override: ${localSkillPath}`)
+      try {
+        const skillContent = fs.readFileSync(localSkillPath, 'utf8')
+        const parsed = parseSkillFile(skillContent)
+        skill = {
+          id: toolId,
+          outputFiles: parsed.output,
+          template: parsed.template,
+          required: parsed.sections.required,
+          optional: parsed.sections.optional,
+        }
+      } catch (err) {
+        console.error(`   ❌ [${toolId}] Failed to parse local skill: ${err.message}`)
+        failCount++
+        continue
+      }
+    } else {
+      skill = BUILT_IN_SKILLS[toolId]
+    }
+
+    if (!skill) {
+      console.error(`   ❌ [${toolId}] Skill not found.`)
+      failCount++
+      continue
+    }
+
+    // Check required sections for this skill
+    const missingRequired = skill.required.filter((s) => {
+      const sectionName = Object.keys(sections).find(
+        (k) => k.toLowerCase() === s.toLowerCase()
+      )
+      return !sectionName || !sections[sectionName]?.trim()
+    })
+
+    if (missingRequired.length > 0) {
+      console.warn(`   ⚠️  [${toolId}] Skipping — missing required sections: ${missingRequired.join(', ')}`)
+      failCount++
+      continue
+    }
+
+    // Render the template
+    let rendered
+    try {
+      rendered = renderTemplate(skill.template, sections, path.relative(cwd, sourcePath) || 'pluribus.md')
+    } catch (err) {
+      console.error(`   ❌ [${toolId}] Template rendering failed: ${err.message}`)
+      failCount++
+      continue
+    }
+
+    // Write output files
+    for (const outputFile of skill.outputFiles) {
+      const outputPath = path.join(cwd, outputFile)
+
+      if (isDryRun) {
+        console.log(`   📝 [dry-run] Would write: ${outputFile}`)
+        console.log('   ' + '─'.repeat(60))
+        const preview = rendered.split('\n').slice(0, 20).join('\n   ')
+        console.log('   ' + preview)
+        if (rendered.split('\n').length > 20) {
+          console.log(`   ... (${rendered.split('\n').length - 20} more lines)`)
+        }
+        console.log('   ' + '─'.repeat(60))
+        console.log('')
+      } else {
+        try {
+          // Ensure parent directory exists
+          const outputDir = path.dirname(outputPath)
+          if (!fs.existsSync(outputDir)) {
+            fs.mkdirSync(outputDir, { recursive: true })
+          }
+          fs.writeFileSync(outputPath, rendered, 'utf8')
+          console.log(`   ✅ [${toolId}] → ${outputFile}`)
+          successCount++
+        } catch (err) {
+          console.error(`   ❌ [${toolId}] Failed to write ${outputFile}: ${err.message}`)
+          failCount++
+        }
+      }
+    }
+  }
+
+  console.log('')
+
+  if (isDryRun) {
+    console.log(`📝 Dry run complete — no files were written.`)
+  } else {
+    if (failCount === 0) {
+      console.log(`✅ Sync complete — ${successCount} file(s) written.`)
+    } else {
+      console.log(`✅ Sync complete — ${successCount} file(s) written, ${failCount} skipped/failed.`)
+    }
+  }
+}

package/src/commands/validate.js

@@ -0,0 +1,146 @@
+/**
+ * pluribus validate — check pluribus.md before sync.
+ *
+ * Validation intentionally mirrors sync's source/import behavior, but it does
+ * not render or write tool output. Remote imports are only refreshed when
+ * --update-imports is passed; otherwise locked remote imports must resolve from
+ * the local lock/cache path.
+ */
+
+import * as fs from 'fs'
+import * as path from 'path'
+import { parsePluribusFile, validateSections, REQUIRED_SECTIONS } from '../utils/parser.js'
+import { resolveImportsAsync } from '../utils/imports.js'
+import { SUPPORTED_TOOLS } from '../skills/built-in.js'
+
+const TOOLS_COMMENT_RE = /<!--\s*pluribus:tools:\s*([^-]+)\s*-->/
+
+/**
+ * @param {Record<string, string | boolean>} args
+ */
+export async function runValidate(args) {
+  const sourceArg = typeof args.source === 'string' ? args.source : null
+  const updateImports = Boolean(args['update-imports'])
+  const cwd = process.cwd()
+  const sourcePath = sourceArg
+    ? path.resolve(cwd, sourceArg)
+    : path.join(cwd, 'pluribus.md')
+
+  const errors = []
+  const warnings = []
+
+  if (!fs.existsSync(sourcePath)) {
+    console.error(`❌ pluribus.md not found at: ${sourcePath}`)
+    console.error('   Run `pluribus init` to create one.')
+    process.exit(1)
+  }
+
+  let rawContent
+  try {
+    rawContent = fs.readFileSync(sourcePath, 'utf8')
+  } catch (err) {
+    console.error(`❌ Could not read ${sourcePath}: ${err.message}`)
+    process.exit(1)
+  }
+
+  console.log(`✓ Found ${path.relative(cwd, sourcePath) || 'pluribus.md'}`)
+
+  const duplicateSections = findDuplicateSections(rawContent)
+  for (const duplicate of duplicateSections) {
+    errors.push(`Duplicate section: # ${duplicate.name} (lines ${duplicate.firstLine} and ${duplicate.line})`)
+  }
+
+  const rawSections = parsePluribusFile(rawContent)
+  if (Object.keys(rawSections).length === 0) {
+    errors.push('No top-level sections found. Add required # Identity, # Stack, # Conventions, # Goals, and # Constraints sections.')
+  } else {
+    console.log(`✓ Detected ${Object.keys(rawSections).length} top-level section(s) before imports`)
+  }
+
+  const tools = parseToolsComment(rawContent)
+  if (tools.length > 0) {
+    const unknownTools = tools.filter((tool) => !SUPPORTED_TOOLS.includes(tool))
+    if (unknownTools.length > 0) {
+      errors.push(`Unknown tool(s) in pluribus:tools comment: ${unknownTools.join(', ')}. Supported: ${SUPPORTED_TOOLS.join(', ')}`)
+    } else {
+      console.log(`✓ Tools comment is valid: ${tools.join(', ')}`)
+    }
+  }
+
+  let resolvedContent
+  let importCount = 0
+  try {
+    const projectDir = path.dirname(sourcePath)
+    const resolved = await resolveImportsAsync(sourcePath, {
+      rootDir: projectDir,
+      allowRemote: updateImports,
+      lockfilePath: path.join(projectDir, 'pluribus.lock.json'),
+      cacheDir: path.join(projectDir, '.pluribus', 'cache', 'remote'),
+      updateLockfile: updateImports,
+    })
+    resolvedContent = resolved.content
+    importCount = resolved.imports.length
+    console.log(`✓ Imports resolved (${importCount})${updateImports ? ' with refresh enabled' : ''}`)
+  } catch (err) {
+    errors.push(`Could not resolve imports: ${err.message}`)
+  }
+
+  if (resolvedContent) {
+    const sections = parsePluribusFile(resolvedContent)
+    const validation = validateSections(sections)
+    for (const error of validation.errors) {
+      errors.push(error)
+    }
+
+    const missingRecommended = REQUIRED_SECTIONS.filter((section) => !sections[section]?.trim())
+    if (missingRecommended.length === 0) {
+      console.log(`✓ Required sections are present: ${REQUIRED_SECTIONS.join(', ')}`)
+    }
+  }
+
+  for (const warning of warnings) {
+    console.warn(`⚠️  ${warning}`)
+  }
+
+  if (errors.length > 0) {
+    console.error('')
+    for (const error of errors) {
+      console.error(`✗ ${error}`)
+    }
+    console.error(`\nFound ${errors.length} error(s). Fix before syncing.`)
+    process.exit(1)
+  }
+
+  console.log('')
+  console.log('✅ pluribus.md is valid. Ready to sync.')
+}
+
+function findDuplicateSections(content) {
+  const cleaned = content.replace(/^\uFEFF/, '')
+  const seen = new Map()
+  const duplicates = []
+  const lines = cleaned.split(/\r?\n/)
+
+  lines.forEach((line, idx) => {
+    if (!line.startsWith('# ') || line.startsWith('## ')) return
+    const name = line.slice(2).trim()
+    const key = name.toLowerCase()
+    const lineNumber = idx + 1
+    if (seen.has(key)) {
+      duplicates.push({ name, firstLine: seen.get(key), line: lineNumber })
+    } else {
+      seen.set(key, lineNumber)
+    }
+  })
+
+  return duplicates
+}
+
+function parseToolsComment(content) {
+  const match = content.match(TOOLS_COMMENT_RE)
+  if (!match) return []
+  return match[1]
+    .split(',')
+    .map((tool) => tool.trim().toLowerCase())
+    .filter(Boolean)
+}

package/src/commands/watch.js

@@ -0,0 +1,111 @@
+/**
+ * pluribus watch — monitor pluribus.md and re-run sync after edits.
+ *
+ * This intentionally uses Node's built-in fs.watch instead of an external
+ * dependency. The watcher is narrow by design: it watches the selected source
+ * file and debounces rapid editor save events before delegating to sync.
+ */
+
+import * as fs from 'fs'
+import * as path from 'path'
+import { runSync } from './sync.js'
+
+const DEFAULT_DEBOUNCE_MS = 400
+
+/**
+ * @param {Record<string, string | boolean>} args
+ */
+export async function runWatch(args) {
+  const sourceArg = typeof args.source === 'string' ? args.source : null
+  const debounceArg = typeof args.debounce === 'string' ? Number(args.debounce) : null
+  const debounceMs = Number.isFinite(debounceArg) && debounceArg >= 300
+    ? debounceArg
+    : DEFAULT_DEBOUNCE_MS
+  const once = Boolean(args.once)
+  const cwd = process.cwd()
+  const sourcePath = sourceArg
+    ? path.resolve(cwd, sourceArg)
+    : path.join(cwd, 'pluribus.md')
+  const sourceDir = path.dirname(sourcePath)
+  const sourceFile = path.basename(sourcePath)
+  const displayPath = path.relative(cwd, sourcePath) || sourceFile
+
+  if (!fs.existsSync(sourcePath)) {
+    console.error(`❌ pluribus.md not found at: ${sourcePath}`)
+    console.error('   Run `pluribus init` to create one.')
+    process.exit(1)
+  }
+
+  let debounceTimer = null
+  let running = false
+  let pending = false
+  let stopped = false
+
+  const syncArgs = { ...args }
+  delete syncArgs.once
+  delete syncArgs.debounce
+
+  const watcher = fs.watch(sourceDir, { persistent: true }, (_eventType, filename) => {
+    if (stopped) return
+    if (filename && filename.toString() !== sourceFile) return
+    scheduleSync()
+  })
+
+  console.log(`👀 Watching ${displayPath} for changes...`)
+  console.log(`   Debounce: ${debounceMs}ms${once ? ' | once mode enabled' : ''}`)
+  console.log('   Press Ctrl+C to stop.')
+  console.log('')
+
+  watcher.on('error', (err) => {
+    console.error(`❌ Watcher failed: ${err.message}`)
+    process.exit(1)
+  })
+
+  process.once('SIGINT', () => {
+    stopped = true
+    if (debounceTimer) clearTimeout(debounceTimer)
+    watcher.close()
+    console.log('\n👋 Stopped watching.')
+    process.exit(0)
+  })
+
+  function scheduleSync() {
+    if (debounceTimer) clearTimeout(debounceTimer)
+    debounceTimer = setTimeout(() => {
+      debounceTimer = null
+      void runDebouncedSync()
+    }, debounceMs)
+  }
+
+  async function runDebouncedSync() {
+    if (running) {
+      pending = true
+      return
+    }
+
+    running = true
+    const timestamp = new Date().toLocaleTimeString('en-GB', { hour12: false })
+    console.log(`[${timestamp}] Change detected, syncing...`)
+
+    try {
+      await runSync(syncArgs)
+      const doneAt = new Date().toLocaleTimeString('en-GB', { hour12: false })
+      console.log(`[${doneAt}] Done.`)
+    } catch (err) {
+      console.error(`❌ Sync failed: ${err.message || err}`)
+    } finally {
+      running = false
+    }
+
+    if (once) {
+      stopped = true
+      watcher.close()
+      process.exit(0)
+    }
+
+    if (pending) {
+      pending = false
+      scheduleSync()
+    }
+  }
+}

package/src/index.js

@@ -0,0 +1,11 @@
+/**
+ * Pluribus — public API surface (for future programmatic use)
+ */
+
+export { runInit } from './commands/init.js'
+export { runSync } from './commands/sync.js'
+export { runValidate } from './commands/validate.js'
+export { runWatch } from './commands/watch.js'
+export { parsePluribusFile, validateSections } from './utils/parser.js'
+export { renderTemplate } from './utils/renderer.js'
+export { BUILT_IN_SKILLS, SUPPORTED_TOOLS } from './skills/built-in.js'