@zenbuild/zenbuild 0.1.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 0xendale
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/index.js

@@ -1,52 +1,99 @@
 #!/usr/bin/env node
-import { spawn }          from 'child_process'
-import { checkNight,
-         checkBurnout,
-         checkHydration } from './lib/gates.js'
-import { breathe }        from './lib/breath.js'
-import { randomQuote }    from './lib/snippets.js'
+import { spawn }                                                  from 'child_process'
+import { checkNight, checkBurnout, pickGate, getHistory,
+         hydrationGate, stretchGate, eyeRestGate, gratitudeGate,
+         maybePosture, readGratitude }                            from './lib/gates.js'
+import { breathe, intro, ripple }                                 from './lib/anim.js'
+import { fetchQuote }                                             from './lib/quotes-api.js'
+import { growGarden, showGarden, growthNotice }                   from './lib/garden.js'
 
+const VERSION = '0.2.0'
 const RESET = '\x1b[0m'
 const BOLD  = '\x1b[1m'
 const DIM   = '\x1b[2m'
 const GREEN = '\x1b[32m'
 const SEP   = `  ${DIM}${'─'.repeat(44)}${RESET}`
 
-function header() {
-  console.log()
-  console.log(`        ${DIM}( zen )${RESET}`)
-  console.log(`     ${DIM}∿∿∿  ◯  ∿∿∿${RESET}`)
-  console.log(`   ${BOLD}zenbuild v0.1.0${RESET}`)
-  console.log(`   ${DIM}"slow down to code faster"${RESET}`)
-  console.log(SEP)
+const arg = process.argv[2]
+
+if (arg === '--garden') {
+  showGarden()
+  process.exit(0)
 }
 
-const cmd = process.argv[2]
+if (arg === '--gratitude') {
+  const entries = readGratitude()
+  if (entries.length === 0) {
+    console.log(`\n  ${DIM}no gratitude noted yet. it will come.${RESET}\n`)
+  } else {
+    console.log(`\n  ${BOLD}things that worked${RESET}\n`)
+    for (const line of entries) {
+      const [date, ...rest] = line.split(' — ')
+      console.log(`  ${DIM}${date.slice(0, 10)}${RESET}  ${rest.join(' — ')}`)
+    }
+    console.log()
+  }
+  process.exit(0)
+}
 
-if (!cmd) {
+if (!arg) {
   console.log(`\n  ${BOLD}Usage:${RESET}   zenbuild ${DIM}"<your build command>"${RESET}`)
-  console.log(`  ${DIM}Example: zenbuild "npm run build"${RESET}\n`)
+  console.log(`  ${DIM}Example: zenbuild "npm run build"${RESET}`)
+  console.log(`  ${DIM}Also:    zenbuild --garden · zenbuild --gratitude${RESET}\n`)
   process.exit(1)
 }
 
-header()
+await intro(VERSION)
+console.log(SEP)
 checkNight()
 console.log(SEP)
 await checkBurnout()
+maybePosture()
 console.log(SEP)
+
+const quotePromise = fetchQuote() // resolves during the breathing ritual
 await breathe()
 console.log(SEP)
-await checkHydration()
-console.log(SEP)
-console.log(`\n  ${BOLD}✦ "${randomQuote()}"${RESET}\n`)
+
+const gate = process.stdout.isTTY ? pickGate(getHistory()) : null
+if (gate === 'eye-rest')       await eyeRestGate()
+else if (gate === 'hydration') {
+  await ripple()
+  await hydrationGate()
+}
+else if (gate === 'stretch')   await stretchGate()
+else if (gate === 'gratitude') await gratitudeGate()
+if (gate) console.log(SEP)
+
+const quote = await quotePromise
+console.log(`\n  ${BOLD}✦ "${quote.text}"${RESET}`)
+if (quote.author) console.log(`    ${DIM}— ${quote.author}${RESET}`)
+console.log()
 await new Promise(r => setTimeout(r, 1500))
 console.log(SEP)
 console.log(`\n  ${GREEN}▶  Okay okay, building now...${RESET}\n`)
 
-const child = spawn(cmd, { shell: true, stdio: 'inherit' })
+const child = spawn(arg, { shell: true, stdio: 'inherit' })
+
+child.on('close', code => {
+  const exitCode = code ?? 0
+  if (exitCode === 0) {
+    const growth = growGarden()
+    if (growth) {
+      console.log(`\n  ${GREEN}${growthNotice(growth.type, growth.total)}${RESET}`)
+      if (growth.completed) {
+        console.log(`  ${DIM}your garden is complete. it was never about the garden.${RESET}\n`)
+      } else {
+        console.log(`  ${DIM}zenbuild --garden to visit${RESET}\n`)
+      }
+    }
+  } else {
+    console.log(`\n  ${DIM}breathe. read the error. it's telling you something.${RESET}\n`)
+  }
+  process.exit(exitCode)
+})
 
-child.on('close', code => process.exit(code ?? 0))
-child.on('error', err  => {
+child.on('error', err => {
   console.error(`\n  ${BOLD}zenbuild:${RESET} could not run command — ${err.message}\n`)
   process.exit(1)
 })

package/lib/anim.js

@@ -0,0 +1,144 @@
+// lib/anim.js
+import { stdout } from 'process'
+
+const RESET = '\x1b[0m'
+const BOLD  = '\x1b[1m'
+const DIM   = '\x1b[2m'
+const GREEN = '\x1b[32m'
+
+const sleep = ms => new Promise(r => setTimeout(r, ms))
+
+// ── breathing circle ──────────────────────────────────────────────────────────
+// 5 frames, radius 1..5. Fixed 5-line height and constant line width so the
+// animation can redraw in place with cursor-up.
+
+const CIRCLE_FRAMES = [
+  [
+    '                   ',
+    '                   ',
+    '         ◯         ',
+    '                   ',
+    '                   ',
+  ],
+  [
+    '                   ',
+    '         ·         ',
+    '       · ◯ ·       ',
+    '         ·         ',
+    '                   ',
+  ],
+  [
+    '        · ·        ',
+    '      ·     ·      ',
+    '     ·   ◯   ·     ',
+    '      ·     ·      ',
+    '        · ·        ',
+  ],
+  [
+    '       ∙ ∙ ∙       ',
+    '     ∙       ∙     ',
+    '    ∙    ◯    ∙    ',
+    '     ∙       ∙     ',
+    '       ∙ ∙ ∙       ',
+  ],
+  [
+    '      ∙  ∙  ∙      ',
+    '    ∙         ∙    ',
+    '   ∙     ◯     ∙   ',
+    '    ∙         ∙    ',
+    '      ∙  ∙  ∙      ',
+  ],
+]
+
+export function circleFrame(radius) {
+  const r = Math.min(Math.max(radius, 1), 5)
+  return CIRCLE_FRAMES[r - 1].join('\n')
+}
+
+// 5 circle lines + blank + label line
+const FRAME_H = 7
+
+function drawBreathFrame(radius, label, dim = false) {
+  const tint  = dim ? DIM : GREEN
+  const block = circleFrame(radius)
+    .split('\n')
+    .map(l => `   ${tint}${l}${RESET}\x1b[K`)
+    .join('\n')
+  stdout.write(`\x1b[${FRAME_H}A\r` + block + `\n\n   ${BOLD}${label.padEnd(12)}${RESET}\x1b[K\n`)
+}
+
+async function animateBreath() {
+  stdout.write('\n'.repeat(FRAME_H))
+  for (let r = 1; r <= 5; r++) {        // inhale: 4s
+    drawBreathFrame(r, 'Inhale...')
+    await sleep(800)
+  }
+  for (let i = 0; i < 4; i++) {         // hold: 2s, pulse
+    drawBreathFrame(5, 'Hold...', i % 2 === 1)
+    await sleep(500)
+  }
+  for (let r = 5; r >= 1; r--) {        // exhale: 4s
+    drawBreathFrame(r, 'Exhale...')
+    await sleep(800)
+  }
+}
+
+export async function breathe() {
+  console.log(`\n  🫁 ${BOLD}Breathe with me for a moment...${RESET}\n`)
+  if (!stdout.isTTY) {
+    for (const [label, ms] of [['Inhale...', 4000], ['Hold...', 2000], ['Exhale...', 4000]]) {
+      console.log(`   ${label}`)
+      await sleep(ms)
+    }
+    console.log()
+    return
+  }
+  await animateBreath()
+  console.log()
+}
+
+// ── animated intro ────────────────────────────────────────────────────────────
+
+const TAGLINE = '"slow down to code faster"'
+
+export async function intro(version) {
+  console.log()
+  if (!stdout.isTTY) {
+    console.log(`        ${DIM}( zen )${RESET}`)
+    console.log(`     ${DIM}∿∿∿  ◯  ∿∿∿${RESET}`)
+    console.log(`   ${BOLD}zenbuild v${version}${RESET}`)
+    console.log(`   ${DIM}${TAGLINE}${RESET}`)
+    return
+  }
+  const waveFrames = [
+    `     ${DIM}·∿·  ·  ·∿·${RESET}`,
+    `     ${DIM}∿∿·  ○  ·∿∿${RESET}`,
+    `     ${DIM}∿∿∿  ◯  ∿∿∿${RESET}`,
+  ]
+  console.log(`        ${DIM}( zen )${RESET}`)
+  stdout.write('\n')
+  for (const frame of waveFrames) {
+    stdout.write(`\x1b[1A\r${frame}\x1b[K\n`)
+    await sleep(250)
+  }
+  console.log(`   ${BOLD}zenbuild v${version}${RESET}`)
+  stdout.write(`   ${DIM}`)
+  for (const ch of TAGLINE) {           // type out, ~30ms/char
+    stdout.write(ch)
+    await sleep(25)
+  }
+  stdout.write(`${RESET}\n`)
+}
+
+// ── water ripple (hydration gate opener) ──────────────────────────────────────
+
+export async function ripple() {
+  if (!stdout.isTTY) return
+  const frames = ['   💧', '    ◦', '  ◦ ◯ ◦', ' ◦  ◯  ◦']
+  stdout.write('\n')
+  for (const f of frames) {
+    stdout.write(`\r\x1b[K  ${DIM}${f}${RESET}`)
+    await sleep(200)
+  }
+  stdout.write('\r\x1b[K')
+}

package/lib/garden.js

@@ -0,0 +1,121 @@
+// lib/garden.js
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs'
+import { homedir } from 'os'
+import { join } from 'path'
+
+const RESET = '\x1b[0m'
+const BOLD  = '\x1b[1m'
+const DIM   = '\x1b[2m'
+
+const GARDEN_DIR  = join(homedir(), '.zenbuild')
+const GARDEN_FILE = join(GARDEN_DIR, 'garden.json')
+
+export const GRID_W = 44
+export const GRID_H = 6
+export const MAX_ELEMENTS = 40
+
+const CYCLE  = ['stone', 'sprout', 'grass', 'bamboo', 'tree', 'lotus']
+const GLYPHS = {
+  stone: '◦', sprout: '🌱', grass: 'ⁿ', bamboo: '┃',
+  tree: '🌲', lotus: '✿', koi: '🐟',
+}
+const NOTICES = {
+  stone:  'a stone settles in your garden',
+  sprout: 'a sprout takes root in your garden',
+  grass:  'grass whispers up through the sand',
+  bamboo: 'bamboo rises in your garden',
+  tree:   'a tree stands quietly in your garden',
+  lotus:  'a lotus blooms in your garden',
+  koi:    'a koi arrives — rare and unbothered',
+}
+
+// ── pure core ─────────────────────────────────────────────────────────────────
+
+export function nextElementType(count) {
+  if ((count + 1) % 10 === 0) return 'koi'
+  return CYCLE[count % CYCLE.length]
+}
+
+export function parseGarden(raw) {
+  try {
+    const data = JSON.parse(raw)
+    if (!Array.isArray(data.elements)) throw new Error('bad shape')
+    return {
+      elements:    data.elements,
+      totalBuilds: Number(data.totalBuilds) || 0,
+      plantedAt:   data.plantedAt || new Date().toISOString(),
+    }
+  } catch {
+    return { elements: [], totalBuilds: 0, plantedAt: new Date().toISOString() }
+  }
+}
+
+export function placeElement(elements, rng = Math.random) {
+  for (let i = 0; i < 200; i++) {
+    const x = Math.floor(rng() * GRID_W)
+    const y = Math.floor(rng() * GRID_H)
+    if (!elements.some(e => e.x === x && e.y === y)) return { x, y }
+  }
+  return null
+}
+
+export function renderGarden(state) {
+  const grid = Array.from({ length: GRID_H }, () => Array(GRID_W).fill(`${DIM}˜${RESET}`))
+  for (const e of state.elements) {
+    if (e.y >= 0 && e.y < GRID_H && e.x >= 0 && e.x < GRID_W) {
+      grid[e.y][e.x] = GLYPHS[e.type] || '◦'
+    }
+  }
+  return grid.map(row => '  ' + row.join('')).join('\n')
+}
+
+export function growthNotice(type, total) {
+  return `${GLYPHS[type]} ${NOTICES[type]} (${total} element${total === 1 ? '' : 's'})`
+}
+
+// ── IO shell ──────────────────────────────────────────────────────────────────
+
+function loadGarden() {
+  try {
+    return parseGarden(readFileSync(GARDEN_FILE, 'utf8'))
+  } catch {
+    return parseGarden('')
+  }
+}
+
+function saveGarden(state, file = GARDEN_FILE) {
+  if (!existsSync(GARDEN_DIR)) mkdirSync(GARDEN_DIR, { recursive: true })
+  writeFileSync(file, JSON.stringify(state, null, 2))
+}
+
+// Adds one element after a successful build. Archives + resets a full garden.
+// Silent null on any failure — the garden never blocks a build.
+export function growGarden(rng = Math.random) {
+  try {
+    const state = loadGarden()
+    const type  = nextElementType(state.elements.length)
+    const pos   = placeElement(state.elements, rng)
+    if (!pos) return null
+    state.elements.push({ type, x: pos.x, y: pos.y, addedAt: new Date().toISOString() })
+    state.totalBuilds += 1
+    const completed = state.elements.length >= MAX_ELEMENTS
+    if (completed) {
+      let n = 1
+      while (existsSync(join(GARDEN_DIR, `garden-${n}.json`))) n++
+      saveGarden(state, join(GARDEN_DIR, `garden-${n}.json`))
+      saveGarden({ elements: [], totalBuilds: state.totalBuilds, plantedAt: new Date().toISOString() })
+    } else {
+      saveGarden(state)
+    }
+    return { type, total: state.elements.length, completed }
+  } catch {
+    return null
+  }
+}
+
+export function showGarden() {
+  const state = loadGarden()
+  console.log(`\n  ${BOLD}your zen garden${RESET}\n`)
+  console.log(renderGarden(state))
+  console.log(`\n  ${DIM}${state.elements.length} elements · ${state.totalBuilds} mindful builds · planted ${state.plantedAt.slice(0, 10)}${RESET}\n`)
+}

package/lib/gates.js

@@ -1,6 +1,6 @@
 // lib/gates.js
 import { createInterface }                    from 'readline'
-import { readFileSync, writeFileSync,
+import { readFileSync, writeFileSync, appendFileSync,
          mkdirSync, existsSync }               from 'fs'
 import { homedir }                             from 'os'
 import { join }                                from 'path'
@@ -15,6 +15,8 @@ const HISTORY_DIR  = join(homedir(), '.zenbuild')
 const HISTORY_FILE = join(HISTORY_DIR, 'history.json')
 const TEN_MIN_MS   = 10 * 60 * 1000
 const MAX_BUILDS   = 5
+const ONE_HOUR_MS    = 60 * 60 * 1000
+const GRATITUDE_FILE = join(HISTORY_DIR, 'gratitude.log')
 
 // ── internal helpers ──────────────────────────────────────────────────────────
 
@@ -62,9 +64,10 @@ export function checkNight() {
 }
 
 export async function checkBurnout() {
-  const now    = Date.now()
-  const raw    = readHistory()
-  const recent = raw.filter(ts => now - new Date(ts).getTime() < TEN_MIN_MS)
+  const now      = Date.now()
+  const raw      = readHistory()
+  const pastHour = raw.filter(ts => now - new Date(ts).getTime() < ONE_HOUR_MS)
+  const recent   = pastHour.filter(ts => now - new Date(ts).getTime() < TEN_MIN_MS)
 
   if (recent.length >= MAX_BUILDS) {
     console.log(`\n  ${YELLOW}🔥 Five builds in ten minutes.`)
@@ -76,15 +79,29 @@ export async function checkBurnout() {
     process.exit(0)
   }
 
-  recent.push(new Date().toISOString())
-  writeHistory(recent)
+  pastHour.push(new Date().toISOString())
+  writeHistory(pastHour)
 }
 
-export async function checkHydration() {
-  if (Math.random() >= 0.1) return
+export function getHistory() {
+  return readHistory()
+}
 
-  const rl = createInterface({ input: process.stdin, output: process.stdout })
+// One roll per run. Eye-rest is not random: it fires on every 3rd build in
+// the rolling hour (3rd, 6th, 9th ...) and replaces the roll entirely.
+export function pickGate(history, rng = Math.random, now = Date.now()) {
+  const pastHour = history.filter(ts => now - new Date(ts).getTime() < ONE_HOUR_MS)
+  if (pastHour.length >= 3 && pastHour.length % 3 === 0) return 'eye-rest'
+  const roll = rng()
+  if (roll < 0.10) return 'hydration'
+  if (roll < 0.20) return 'stretch'
+  if (roll < 0.25) return 'gratitude'
+  return null
+}
 
+// Hydration prompt without the probability roll — pickGate owns probability.
+export async function hydrationGate() {
+  const rl = createInterface({ input: process.stdin, output: process.stdout })
   return new Promise(resolve => {
     const ask = () => {
       rl.question(
@@ -110,3 +127,70 @@ export async function checkHydration() {
     ask()
   })
 }
+
+const STRETCHES = [
+  'roll your neck slowly, side to side',
+  'shrug your shoulders up... and let them drop',
+  'circle your wrists — builders need their wrists',
+  'stand up and reach for the ceiling',
+]
+
+export async function stretchGate(rng = Math.random) {
+  const s = STRETCHES[Math.floor(rng() * STRETCHES.length)]
+  console.log(`\n  ${GREEN}🧘 quick stretch: ${s}${RESET}\n`)
+  await countdown(15)
+}
+
+export async function eyeRestGate() {
+  console.log(`\n  ${GREEN}👀 you've been at this a while.`)
+  console.log(`     look at something 20 feet away. just 20 seconds.${RESET}\n`)
+  await countdown(20)
+}
+
+export function formatGratitudeEntry(text, date = new Date()) {
+  return `${date.toISOString()} — ${text}\n`
+}
+
+function appendGratitude(text) {
+  try {
+    if (!existsSync(HISTORY_DIR)) mkdirSync(HISTORY_DIR, { recursive: true })
+    appendFileSync(GRATITUDE_FILE, formatGratitudeEntry(text))
+  } catch {} // gratitude never blocks a build
+}
+
+export async function gratitudeGate() {
+  const rl = createInterface({ input: process.stdin, output: process.stdout })
+  return new Promise(resolve => {
+    rl.question(`\n  ${GREEN}🙏 name one thing that worked today: ${RESET}`, (answer) => {
+      rl.close()
+      const text = answer.trim()
+      if (text) {
+        appendGratitude(text)
+        console.log(`\n  ${DIM}noted. carry it with you.${RESET}`)
+      }
+      resolve()
+    })
+  })
+}
+
+export function readGratitude() {
+  try {
+    return readFileSync(GRATITUDE_FILE, 'utf8').trim().split('\n').filter(Boolean).reverse()
+  } catch {
+    return []
+  }
+}
+
+const POSTURE_LINES = [
+  '🧘 unclench your jaw. drop your shoulders. sit tall.',
+  '🧘 feet flat. spine long. screen at eye level.',
+  '🧘 relax your grip on the mouse. it already surrendered.',
+]
+
+// Non-blocking flavor, not a gate: ~15% chance, one dim line, no pause.
+export function maybePosture(rng = Math.random) {
+  if (rng() < 0.15) {
+    const line = POSTURE_LINES[Math.floor(rng() * POSTURE_LINES.length)]
+    console.log(`\n  ${DIM}${line}${RESET}`)
+  }
+}

package/lib/quotes-api.js

@@ -0,0 +1,27 @@
+// lib/quotes-api.js
+import { randomQuote } from './snippets.js'
+
+const API_URL = 'https://zenquotes.io/api/random'
+
+// Never rejects, never blocks longer than timeoutMs: any failure falls back
+// silently to the local pool. fetchImpl is injectable for tests.
+export async function fetchQuote(fetchImpl = globalThis.fetch, timeoutMs = 2000) {
+  const ctrl  = new AbortController()
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs)
+  try {
+    const res = await fetchImpl(API_URL, { signal: ctrl.signal })
+    if (!res.ok) throw new Error(`status ${res.status}`)
+    const data = await res.json()
+    const q = data?.[0]?.q
+    const a = data?.[0]?.a
+    if (typeof q !== 'string' || !q.trim()) throw new Error('bad payload')
+    return {
+      text:   q.trim(),
+      author: typeof a === 'string' && a.trim() ? a.trim() : null,
+    }
+  } catch {
+    return { text: randomQuote(), author: null }
+  } finally {
+    clearTimeout(timer)
+  }
+}

package/package.json

@@ -1,17 +1,18 @@
 {
   "name": "@zenbuild/zenbuild",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Slow down to code faster.",
   "type": "module",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/0xendale/zenbuild.git"
   },
+  "homepage": "https://github.com/0xendale/zenbuild#readme",
   "bin": {
     "zenbuild": "./index.js"
   },
   "scripts": {
-    "test": "node --test test/"
+    "test": "node --test"
   },
   "files": [
     "index.js",

package/lib/breath.js

@@ -1,37 +0,0 @@
-// lib/breath.js
-import { stdout } from 'process'
-
-const RESET = '\x1b[0m'
-const GREEN = '\x1b[32m'
-const DIM   = '\x1b[2m'
-const BOLD  = '\x1b[1m'
-const BAR_W = 30
-
-function renderBar(filled) {
-  return GREEN + '█'.repeat(filled) + DIM + '░'.repeat(BAR_W - filled) + RESET
-}
-
-function animatePhase(label, durationMs) {
-  const stepMs = durationMs / BAR_W
-  let filled = 0
-
-  return new Promise(resolve => {
-    const timer = setInterval(() => {
-      filled++
-      stdout.write(`\r   ${BOLD}${label.padEnd(12)}${RESET} [${renderBar(filled)}]`)
-      if (filled >= BAR_W) {
-        clearInterval(timer)
-        stdout.write('\n')
-        resolve()
-      }
-    }, stepMs)
-  })
-}
-
-export async function breathe() {
-  console.log(`\n  🫁 ${BOLD}Breathe with me for a moment...${RESET}\n`)
-  await animatePhase('Inhale...', 4000)
-  await animatePhase('Hold...', 2000)
-  await animatePhase('Exhale...', 4000)
-  console.log()
-}