dev-booster 1.0.0 → 1.1.0

package/README.md

@@ -6,6 +6,12 @@
 npx dev-booster
 ```
 
+To update an existing kit installation safely:
+
+```bash
+npx dev-booster --update
+```
+
 ---
 
 ## What it does
@@ -52,6 +58,20 @@ The AI will:
 
 This process only needs to run once. The `DEVBOOSTER_INIT.md` stays in your project — if you need to re-run after a major architectural change, just ask again.
 
+For later kit updates, use:
+
+```bash
+npx dev-booster --update
+```
+
+This refreshes:
+- `.devbooster/boosters/`
+- `.devbooster/hub/`
+
+And preserves:
+- `.devbooster/rules/`
+- `DEVBOOSTER_INIT.md`
+
 ---
 
 ## Boosters

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dev-booster",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Reusable AI development kit with manual boosters, governance, and project bootstrap",
   "type": "module",
   "scripts": {

package/src/index.js

@@ -1,5 +1,6 @@
 import fs from 'fs'
 import path from 'path'
+import readline from 'readline/promises'
 import { fileURLToPath } from 'url'
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
@@ -9,6 +10,25 @@ const TEMPLATE_DIR = path.resolve(__dirname, '..', 'template')
 
 // Destination: the user's current working directory (where they ran npx)
 const TARGET_DIR = process.cwd()
+const args = process.argv.slice(2)
+const IDE_BRIDGE_BLOCK = [
+  '# 🤖 DEV BOOSTER — AGENTIC KIT BOOTSTRAP',
+  '',
+  'Before any action, read `.devbooster/rules/PROTOCOL.md` for full governance rules.',
+]
+const IDE_BRIDGE_MARKER = '.devbooster/rules/PROTOCOL.md'
+const IDE_BRIDGE_FALLBACK_FLAG = path.join('hub', 'flags', 'needs-ide-bridge')
+const IDE_BRIDGE_TARGETS = [
+  '.rules',
+  '.cursorrules',
+  '.windsurfrules',
+  '.clinerules',
+  'AGENT.md',
+  'AGENTS.md',
+  'CLAUDE.md',
+  'GEMINI.md',
+  '.github/copilot-instructions.md',
+]
 
 function copyDir(src, dest) {
   fs.mkdirSync(dest, { recursive: true })
@@ -27,13 +47,149 @@ function copyDir(src, dest) {
   }
 }
 
-export function run() {
+function removeDirContents(targetDir) {
+  if (!fs.existsSync(targetDir)) return
+
+  for (const entry of fs.readdirSync(targetDir, { withFileTypes: true })) {
+    const entryPath = path.join(targetDir, entry.name)
+    fs.rmSync(entryPath, { recursive: true, force: true })
+  }
+}
+
+function syncDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true })
+  removeDirContents(dest)
+  copyDir(src, dest)
+}
+
+function isUpdateMode() {
+  return args.includes('--update') || args.includes('update')
+}
+
+function ensureTrailingNewline(content) {
+  return content.endsWith('\n') ? content : `${content}\n`
+}
+
+function appendUniqueLines(filePath, lines) {
+  const existing = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : ''
+  const normalized = ensureTrailingNewline(existing)
+  const missingLines = lines.filter((line) => !existing.includes(line))
+
+  if (missingLines.length === 0) {
+    return false
+  }
+
+  const nextContent = `${normalized}${missingLines.join('\n')}\n`
+  fs.writeFileSync(filePath, nextContent)
+  return true
+}
+
+async function askYesNo(question, defaultYes = true) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    return defaultYes
+  }
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  })
+
+  try {
+    const suffix = defaultYes ? ' (Y/n) ' : ' (y/N) '
+    const answer = (await rl.question(`${question}${suffix}`)).trim().toLowerCase()
+
+    if (!answer) return defaultYes
+    if (answer === 'y' || answer === 'yes') return true
+    if (answer === 'n' || answer === 'no') return false
+    return defaultYes
+  } finally {
+    rl.close()
+  }
+}
+
+async function maybeAddDevBoosterToGitignore() {
+  const shouldIgnore = await askYesNo('Add Dev Booster to your .gitignore?', true)
+
+  if (!shouldIgnore) {
+    console.log('▸ .gitignore')
+    console.log('  status: skipped by user\n')
+    return
+  }
+
+  const gitignorePath = path.join(TARGET_DIR, '.gitignore')
+  const changed = appendUniqueLines(gitignorePath, ['.devbooster/', 'DEVBOOSTER_INIT.md'])
+
+  console.log('▸ .gitignore')
+  if (changed) {
+    console.log('  status: updated')
+    console.log('  entries: .devbooster/, DEVBOOSTER_INIT.md\n')
+  } else {
+    console.log('  status: already configured')
+    console.log('  entries: .devbooster/, DEVBOOSTER_INIT.md\n')
+  }
+}
+
+function appendUniqueBlock(filePath, blockLines, marker) {
+  const existing = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : ''
+  if (existing.includes(marker)) {
+    return false
+  }
+
+  const normalized = ensureTrailingNewline(existing)
+  const nextContent = `${normalized}${blockLines.join('\n')}\n`
+  fs.mkdirSync(path.dirname(filePath), { recursive: true })
+  fs.writeFileSync(filePath, nextContent)
+  return true
+}
+
+function writeIdeBridgeFallbackFlag() {
+  const flagPath = path.join(TARGET_DIR, '.devbooster', IDE_BRIDGE_FALLBACK_FLAG)
+  fs.mkdirSync(path.dirname(flagPath), { recursive: true })
+  fs.writeFileSync(flagPath, 'create AGENTS.md fallback bridge\n')
+}
+
+function clearIdeBridgeFallbackFlag() {
+  const flagPath = path.join(TARGET_DIR, '.devbooster', IDE_BRIDGE_FALLBACK_FLAG)
+  if (fs.existsSync(flagPath)) {
+    fs.rmSync(flagPath, { force: true })
+  }
+}
+
+function setupIdeBridgeFiles() {
+  const touchedFiles = []
+
+  for (const relativeTarget of IDE_BRIDGE_TARGETS) {
+    const targetPath = path.join(TARGET_DIR, relativeTarget)
+    if (!fs.existsSync(targetPath)) continue
+
+    appendUniqueBlock(targetPath, IDE_BRIDGE_BLOCK, IDE_BRIDGE_MARKER)
+    touchedFiles.push(relativeTarget)
+  }
+
+  console.log('▸ IDE bridge files')
+  if (touchedFiles.length > 0) {
+    clearIdeBridgeFallbackFlag()
+    console.log('  status: bridge instructions appended where applicable')
+    console.log(`  files: ${touchedFiles.join(', ')}\n`)
+    return
+  }
+
+  writeIdeBridgeFallbackFlag()
+  console.log('  status: no known IDE instruction file found')
+  console.log('  action: bootstrap fallback flag created for DEVBOOSTER_INIT.md\n')
+}
+
+function printHeader(subtitle) {
   console.log(`
 ╭──────────────────────────────────────────────╮
 │               DEV BOOSTER                    │
-│        instalador do kit agentico           │
+│ ${subtitle.padEnd(44)} │
 ╰──────────────────────────────────────────────╯
 `)
+}
+
+async function runInstall() {
+  printHeader('agentic kit installer')
 
   // 1. Copy the full .devbooster/ kit to the user's project
   const agentSrc = path.join(TEMPLATE_DIR, '.devbooster')
@@ -41,13 +197,13 @@ export function run() {
 
   if (fs.existsSync(agentDest)) {
     console.log('▸ .devbooster/')
-    console.log('  status: ja existe no projeto')
-    console.log('  acao: copia ignorada para evitar sobrescrita')
-    console.log('  dica: renomeie ou remova a pasta se quiser reinstalar\n')
+    console.log('  status: already exists in this project')
+    console.log('  action: copy skipped to avoid overwrite')
+    console.log('  tip: rename or remove the folder if you want a fresh install\n')
   } else {
     copyDir(agentSrc, agentDest)
     console.log('▸ .devbooster/')
-    console.log('  status: instalado com sucesso\n')
+    console.log('  status: installed successfully\n')
   }
 
   // 2. Drop DEVBOOSTER_INIT.md at the root of the user's project
@@ -56,23 +212,78 @@ export function run() {
 
   if (fs.existsSync(initDest)) {
     console.log('▸ DEVBOOSTER_INIT.md')
-    console.log('  status: ja existe no projeto')
-    console.log('  acao: criacao ignorada\n')
+    console.log('  status: already exists in this project')
+    console.log('  action: creation skipped\n')
   } else {
     fs.copyFileSync(initSrc, initDest)
     console.log('▸ DEVBOOSTER_INIT.md')
-    console.log('  status: criado na raiz do projeto\n')
+    console.log('  status: created at project root\n')
   }
 
+  await maybeAddDevBoosterToGitignore()
+  setupIdeBridgeFiles()
+
   console.log(`
 ╭──────────────────────────────────────────────╮
-│                 PROXIMO PASSO                │
+│                   NEXT STEP                  │
 ╰──────────────────────────────────────────────╯
 
-Abra sua LLM / assistente de IA neste projeto e envie:
+Open your AI assistant in this project and send:
 
-  "Leia o DEVBOOSTER_INIT.md e execute todos os passos de bootstrap."
+  "Read DEVBOOSTER_INIT.md and execute all bootstrap steps."
 
-O kit vai se configurar com base no stack do projeto.
+The kit will configure itself based on your project's stack.
 `)
 }
+
+function runUpdate() {
+  printHeader('safe kit update')
+
+  const kitRoot = path.join(TARGET_DIR, '.devbooster')
+  const templateRoot = path.join(TEMPLATE_DIR, '.devbooster')
+
+  if (!fs.existsSync(kitRoot)) {
+    console.log('▸ .devbooster/')
+    console.log('  status: not found in this project')
+    console.log('  action: run `npx dev-booster` first to install the kit\n')
+    return
+  }
+
+  const updateTargets = [
+    { name: 'boosters', src: path.join(templateRoot, 'boosters'), dest: path.join(kitRoot, 'boosters') },
+    { name: 'hub', src: path.join(templateRoot, 'hub'), dest: path.join(kitRoot, 'hub') },
+  ]
+
+  for (const target of updateTargets) {
+    syncDir(target.src, target.dest)
+    console.log(`▸ .devbooster/${target.name}/`)
+    console.log('  status: updated successfully')
+  }
+
+  console.log('')
+  console.log('▸ rules/')
+  console.log('  status: preserved')
+  console.log('  action: no local files were overwritten')
+  console.log('')
+  console.log('▸ DEVBOOSTER_INIT.md')
+  console.log('  status: preserved')
+  console.log('  action: no local files were overwritten\n')
+
+  console.log(`
+╭──────────────────────────────────────────────╮
+│                   NEXT STEP                  │
+╰──────────────────────────────────────────────╯
+
+Review the updated kit files in your project and, if you want,
+reopen your AI assistant to keep working with the refreshed boosters.
+`)
+}
+
+export async function run() {
+  if (isUpdateMode()) {
+    runUpdate()
+    return
+  }
+
+  await runInstall()
+}

package/template/.devbooster/rules/GUIDE.md

@@ -108,4 +108,20 @@ Depois da ativação, envie o próximo passo normalmente.
 Exemplo:
 "[arquivo planning.md enviado no chat]"
 "Agora quero validar se já fechamos contexto suficiente para seguir para implementation."
+
+---
+
+💡 COMO ATUALIZAR O KIT:
+Se este projeto já tem Dev Booster instalado e você quiser receber uma versão mais nova do kit,
+use no terminal:
+
+`npx dev-booster --update`
+
+O update:
+- atualiza `.devbooster/boosters/`
+- atualiza `.devbooster/hub/`
+- preserva `.devbooster/rules/`
+- preserva `DEVBOOSTER_INIT.md`
+
+Isso existe para manter seguras as regras e ajustes locais do projeto.
 ```

package/template/.devbooster/rules/PROTOCOL.md

@@ -1,16 +1,19 @@
 # 🛡️ PROJECT PROTOCOL (GOVERNANCE — SINGLE SOURCE OF TRUTH)
-**Version:** 8.0 | **Focus:** Conduct, Communication, Code Quality & Kit Architecture.
+**Version:** 9.0 | **Focus:** Conduct, Communication, Code Quality & Booster-Guided Work.
 
 ## 👤 0. PERSONA & HIERARCHY
 - **User:** Lead Developer / Project Architect.
 - **AI:** Strict Technical Consultant / Pair-programmer. Execute only upon explicit user authorization.
 
 ## 🏛️ 1. ARCHITECTURAL LINKS
-- **PATH RESOLUTION:** Use repository-relative paths directly from `.devbooster/` and `.devbooster/hub/`.
-- **INVENTORY SEARCH:** Consult `.devbooster/MANIFEST.md` to identify available **Agents**, **Skills**, and **Scripts**.
-- **BOOSTER RELIANCE:** Do not implement complex logic without activating the specific **Booster** (e.g., `implementation.md`, `debug.md`, `design.md`).
-- **PROJECT CONTEXT:** Read `.devbooster/rules/PROJECT.md` for architecture and business rules before any implementation.
-- **USER PATTERNS:** Always read `.devbooster/rules/USER_PREFERENCES.md` before generating code.
+- **KIT ROOT:** Use repository-relative paths from `.devbooster/`.
+- **BOOSTER NAVIGATION:** Use `.devbooster/rules/GUIDE.md` and `.devbooster/MANIFEST.md` as the main references to understand booster usage and available guided paths.
+- **BOOSTER-FIRST PHILOSOPHY:** Dev Booster is manual-first. Boosters are the main guided entry point for complex work.
+- **NO AUTO-LOADING:** Do NOT automatically search for, load, or activate Personas, Skills, or Scripts from the kit just because they exist.
+- **BOOSTER SUGGESTION:** When the task clearly benefits from a checkpoint or guided mode, suggest the most relevant Booster instead of silently routing internal assets.
+- **ACTIVE BOOSTER RULE:** Once a Booster is manually activated, follow that Booster's contract.
+- **PROJECT CONTEXT:** Consult `.devbooster/rules/PROJECT.md` and other local rules when they materially affect the current task.
+- **USER PATTERNS:** Consult `.devbooster/rules/USER_PREFERENCES.md` when the task depends on established user conventions or explicit prior preferences.
 
 ## 🚫 2. NON-NEGOTIABLE BEHAVIORS
 - **NO_CODE:** Discuss and validate plans BEFORE any implementation. Use the Socratic Gate.
@@ -28,8 +31,8 @@
 - **STOP-BY-DEFAULT:** Discussion and validation of plans MUST happen BEFORE implementation.
 - **CRITIQUE MODE:** Validate with architectural rigor. Do not agree for politeness.
 - **BILINGUAL POLICY:**
-    - **Chat:** PT-BR (Brasileiro, Técnico, Direto).
-    - **Logs, Code, Comments, Variables:** English.
+    - **Chat:** Follow the global language configured for the active LLM/environment.
+    - **Logs, Code, Comments, Variables:** English, unless the project explicitly requires another convention.
 
 ## 📚 5. PERSISTENCE (MEMORIALIZATION)
 - **THE TRIGGER:** "bota na enciclopédia".

package/template/DEVBOOSTER_INIT.md

@@ -31,9 +31,25 @@ The file contains a bootstrap prompt. Execute it: scan the backend/API architect
 Read `.devbooster/rules/COMERCIAL.md`.
 The file contains a bootstrap prompt. Execute it: analyze the product's business model and overwrite the file with commercial positioning documentation.
 
-### STEP 6 — Confirm Completion
+### STEP 6 — IDE Bridge Fallback
+The CLI already tries to locate known AI/IDE instruction files and append the Dev Booster bridge automatically.
+
+If the file `.devbooster/hub/flags/needs-ide-bridge` exists, it means no known IDE instruction file was found during installation.
+In that case, create `AGENTS.md` at the project root and insert the following block:
+
+```md
+# 🤖 DEV BOOSTER — AGENTIC KIT BOOTSTRAP
+
+Before any action, read `.devbooster/rules/PROTOCOL.md` for full governance rules.
+```
+
+Do not duplicate the block if the file already references `.devbooster/rules/PROTOCOL.md`.
+If `AGENTS.md` already exists, append the block at the end instead of overwriting the file.
+
+### STEP 7 — Confirm Completion
 After all files have been overwritten, report back to the user with:
 - A summary of what was detected in each domain (project, frontend, backend, commercial).
+- Whether the IDE bridge was already handled by the CLI or whether `AGENTS.md` had to be created as fallback.
 - Any gaps or missing information that could not be auto-detected and may need manual input.
 
 ---