@jgiox/goodvibes 1.4.0 → 1.6.1

package/dist/index.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
+import { createRequire as createRequire2 } from "module";
 import { Command } from "commander";
 
 // src/commands/init.ts
@@ -12,7 +13,7 @@ import { copy } from "fs-extra";
 import { readFile as readFile2, rename } from "fs/promises";
 import { readdir } from "fs/promises";
 import { existsSync } from "fs";
-import { join, relative } from "path";
+import { join, relative, sep } from "path";
 import { fileURLToPath } from "url";
 
 // src/utils/sentinel-merge.ts
@@ -114,6 +115,10 @@ async function copyTemplates(templateDir, destDir, dryRun, minimal, projectType
   }
   const skippedFiles = [];
   const destCiYml = join(destDir, ".github", "workflows", "ci.yml");
+  const workflowPrefix = join(".github", "workflows") + sep;
+  const destHasWorkflows = [...existingBefore].some(
+    (f) => f.startsWith(workflowPrefix) && f.endsWith(".yml")
+  );
   try {
     await copy(templateDir, destDir, {
       overwrite: false,
@@ -127,6 +132,7 @@ async function copyTemplates(templateDir, destDir, dryRun, minimal, projectType
         for (const variant of ciVariants) {
           if (src.endsWith(variant) && variant !== selectedVariant) return false;
         }
+        if (destHasWorkflows && rel.startsWith(workflowPrefix) && src.endsWith(".yml")) return false;
         return true;
       }
     });
@@ -198,6 +204,16 @@ async function installHeadroom(log) {
     log("Python 3.10+ not found \u2014 skipping headroom install. Install Python 3.10+ and run `goodvibes init` again.");
     return;
   }
+  log("headroom compresses AI context to save tokens \u2014 this keeps your costs down and sessions faster.");
+  try {
+    await execa2("headroom", ["--version"]);
+    log("headroom already installed \u2014 skipping");
+    return;
+  } catch (e) {
+    if (e.code !== "ENOENT") {
+      log(`headroom probe failed: ${e.message?.split("\n")[0] ?? "unknown"}`);
+    }
+  }
   log("Note: headroom will download its compression model on first use \u2014 this may take 1\u20133 minutes on a slow connection.");
   const installers = [
     { cmd: "uv", args: ["tool", "install", "headroom-ai[all]"] },
@@ -416,13 +432,6 @@ async function detectInstalledVersion(cwd) {
   const content = await readFile3(claudePath, "utf-8");
   return extractVersion(content);
 }
-async function detectBundledVersion(templateDir) {
-  if (!templateDir) return null;
-  const claudeSrc = join3(templateDir, "CLAUDE.md");
-  if (!await pathExists2(claudeSrc)) return null;
-  const content = await readFile3(claudeSrc, "utf-8");
-  return extractVersion(content);
-}
 async function computeChanges(templateDir, destDir, projectType) {
   const allFiles = await listTemplateFiles(templateDir) ?? [];
   const managedFiles = allFiles.filter(
@@ -479,7 +488,7 @@ async function upgradeTemplates(templateDir, destDir, projectType) {
   return allDest.filter((f) => f.startsWith(".claude/skills/") || f.startsWith(".github/workflows/") || f === "CLAUDE.md").sort();
 }
 function registerUpgradeCommand(program2) {
-  program2.command("upgrade").description("Update goodvibes-managed files to the latest version").option("--dry-run", "Preview what would change without writing").action(async (options) => {
+  program2.command("upgrade").alias("update").description("Update goodvibes-managed files to the latest version").option("--dry-run", "Preview what would change without writing").action(async (options) => {
     const dryRun = options.dryRun ?? false;
     const cwd = process.cwd();
     intro2("goodvibes upgrade");
@@ -502,7 +511,7 @@ function registerUpgradeCommand(program2) {
     const templateDir = resolveTemplatesDir();
     const projectType = detectProjectType(cwd);
     const installedVersion = await detectInstalledVersion(cwd);
-    const bundledVersion = await detectBundledVersion(templateDir);
+    const bundledVersion = getInstalledVersion();
     if (installedVersion && bundledVersion && versionGte(installedVersion, bundledVersion)) {
       outro2(`Already up to date (v${installedVersion})`);
       return;
@@ -529,6 +538,90 @@ function registerUpgradeCommand(program2) {
   });
 }
 
+// src/commands/doctor.ts
+import { note as note3, outro as outro3 } from "@clack/prompts";
+import { existsSync as existsSync4, readFileSync } from "fs";
+import { join as join4 } from "path";
+import { execa as execa5 } from "execa";
+var SENTINEL_START2 = "<!-- goodvibes:start -->";
+var SENTINEL_END2 = "<!-- goodvibes:end -->";
+async function checkHeadroom() {
+  try {
+    await execa5("headroom", ["--version"]);
+    return { label: "headroom on PATH", pass: true };
+  } catch (e) {
+    if (e.code === "ENOENT") {
+      return {
+        label: "headroom on PATH",
+        pass: false,
+        remedy: 'Run: uv tool install "headroom-ai[all]"  (or re-run goodvibes init)'
+      };
+    }
+    throw e;
+  }
+}
+async function checkGit() {
+  const keys = ["user.name", "user.email"];
+  const results = [];
+  for (const key of keys) {
+    try {
+      const { stdout } = await execa5("git", ["config", key]);
+      results.push({
+        label: `git ${key}`,
+        pass: stdout.trim().length > 0,
+        remedy: stdout.trim().length > 0 ? void 0 : `Run: git config --global ${key} "Your Value"`
+      });
+    } catch {
+      results.push({
+        label: `git ${key}`,
+        pass: false,
+        remedy: `Run: git config --global ${key} "Your Value"`
+      });
+    }
+  }
+  return results;
+}
+function checkClaudeMd(cwd) {
+  const present = existsSync4(join4(cwd, "CLAUDE.md"));
+  return {
+    label: "CLAUDE.md present",
+    pass: present,
+    remedy: present ? void 0 : "Run: goodvibes init"
+  };
+}
+function checkSentinel(cwd) {
+  const path = join4(cwd, "CLAUDE.md");
+  if (!existsSync4(path)) {
+    return { label: "goodvibes sentinel block", pass: false, remedy: "Run: goodvibes init" };
+  }
+  const content = readFileSync(path, "utf-8");
+  const ok = content.includes(SENTINEL_START2) && content.includes(SENTINEL_END2);
+  return {
+    label: "goodvibes sentinel block",
+    pass: ok,
+    remedy: ok ? void 0 : "Run: goodvibes init (will merge sentinel block)"
+  };
+}
+function registerDoctorCommand(program2) {
+  program2.command("doctor").description("Check goodvibes setup is complete").action(async () => {
+    const cwd = process.cwd();
+    const headroomResult = await checkHeadroom();
+    const gitResults = await checkGit();
+    const claudeMdResult = checkClaudeMd(cwd);
+    const sentinelResult = checkSentinel(cwd);
+    const all = [headroomResult, ...gitResults, claudeMdResult, sentinelResult];
+    const lines = all.map((r) => `${r.pass ? "\u2713" : "\u2717"} ${r.label}`);
+    note3(lines.join("\n"), "goodvibes doctor");
+    const failures = all.filter((r) => !r.pass);
+    if (failures.length > 0) {
+      const remediation = failures.filter((r) => r.remedy).map((r) => r.remedy).join("\n");
+      note3(remediation, "How to fix");
+      process.exit(1);
+    }
+    outro3("All checks passed.");
+  });
+}
+
 // src/index.ts
 var [major] = process.version.replace("v", "").split(".").map(Number);
 if (major < 20) {
@@ -540,8 +633,11 @@ Install the latest LTS from https://nodejs.org
   );
   process.exit(1);
 }
+var _require2 = createRequire2(import.meta.url);
+var _pkg = _require2("../package.json");
 var program = new Command();
-program.name("goodvibes").version("1.0.0").description("One-command bootstrap for vibe coding projects");
+program.name("goodvibes").version(_pkg.version).description("One-command bootstrap for vibe coding projects");
 registerInitCommand(program);
 registerUpgradeCommand(program);
+registerDoctorCommand(program);
 await program.parseAsync(process.argv);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgiox/goodvibes",
-  "version": "1.4.0",
+  "version": "1.6.1",
   "description": "One-command bootstrap for vibe coding projects",
   "type": "module",
   "bin": {
@@ -40,7 +40,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "commander": "^13",
+    "commander": "^15",
     "@clack/prompts": "^1",
     "fs-extra": "^11",
     "execa": "^9"

package/templates/.bolt/prompt

@@ -0,0 +1,11 @@
+Engineering Rules for this project (goodvibes).
+
+Think before coding. State assumptions before implementing. Stop if an assumption is security-sensitive, schema-sensitive, or has multiple materially different interpretations.
+
+Simplicity first. Stop at the first option that works: Does this need to exist at all? Already in the codebase? Use it. Stdlib covers it? Use it. Can it be one line? One line. Only then write new code. No unrequested abstractions. No boilerplate for later. Deletion over addition.
+
+Surgical changes. Keep diffs narrow. No opportunistic reformats. No renames unless the task requires it. Only remove what your change made unused.
+
+Fail loud. No empty catch blocks. No silent retries. No returning fake success on real failure. Error messages must be actionable and specific.
+
+Security. Validate input at the boundary. Keep secrets out of code and logs. Apply least privilege. Flag immediately: SQL injection, XSS, command injection, path traversal, broken auth, leaked secrets.

package/templates/CLAUDE.md

@@ -1,7 +1,7 @@
 # CLAUDE.md
 
 <!-- goodvibes:start -->
-# goodvibes: v1.3.0
+# goodvibes: v1.6.1
 
 ## Engineering Rules
 

package/templates/docs/getting-started.md

@@ -0,0 +1,31 @@
+# Getting started with goodvibes
+
+You ran `goodvibes init`. Here is what happens next.
+
+## What was set up
+
+goodvibes wrote several files into your project: `CLAUDE.md` with engineering rules and the ponytail minimalism ruleset, AI rule files for your coding tool (Cursor, Windsurf, Kiro, GitHub Copilot, and others), CI workflows for automated quality checks, and docs templates including this one. Everything runs automatically — no configuration needed.
+
+## Your first change
+
+1. **Open your project in your AI coding tool.** Cursor, Windsurf, Kiro, and GitHub Copilot all pick up the goodvibes rules automatically. The AI will follow minimal-code and fail-loud principles from the first message.
+2. **Tell the AI what you want to build.** Describe the feature in plain language — the rules guide the AI to keep code simple and surgical.
+3. **Review the diff before you commit.** Check that the AI only changed what you asked. The rules encourage narrow diffs — if the change looks too large, ask the AI to trim it.
+4. **Run `git add . && git commit -m "feat: your change here"`.** This saves a checkpoint in your project history so you can always go back.
+5. **Run `git push`.** This sends your work to GitHub, where it is safe even if your machine breaks.
+
+## Check your setup
+
+Run `goodvibes doctor` to verify everything is working. It checks that headroom is installed, your git identity is configured, and the goodvibes rules are in place.
+
+## Useful commands
+
+| Command | What it does |
+|---------|--------------|
+| `goodvibes update` | Re-sync goodvibes files to the latest version |
+| `goodvibes doctor` | Check that headroom, git, and rules are all working |
+| `goodvibes upgrade --dry-run` | Preview what `goodvibes update` would change |
+
+## What is headroom?
+
+headroom compresses the AI's memory of your project so you spend fewer tokens per session. It runs automatically in the background when Claude Code is active — you do not need to invoke it manually.

package/templates/docs/platform-setup/base44.md

@@ -0,0 +1,40 @@
+# Base44 — goodvibes setup
+
+Base44 does not read files from your project. Instead, you paste your rules into the AI controls panel, and Base44 applies them to every AI interaction in that project.
+
+## Steps
+
+1. Go to [base44.com](https://base44.com) and sign in.
+2. Open your project.
+3. Find the **AI controls** panel — it is usually in the top-right corner or under project Settings.
+4. Click **Custom Instructions**.
+5. Paste the text below into the box.
+6. Click **Save**.
+
+That is it. From now on, every AI action in this project follows the goodvibes engineering rules.
+
+> If the steps above do not match what you see, look for **Custom Instructions** or **AI controls** in the project settings. The UI may change — the paste text stays the same.
+
+> **Base44 Skills** is a separate feature for saving reusable instruction sets. goodvibes does not require it — pasting into Custom Instructions is enough.
+
+---
+
+## Paste this text
+
+```
+Engineering Rules — goodvibes
+
+Think before coding. State assumptions before implementing. Stop if an assumption is security-sensitive, schema-sensitive, or has multiple materially different interpretations.
+
+Simplicity first. Stop at the first option that works: Does this need to exist at all? Already in the codebase? Use it. Stdlib covers it? Use it. Can it be one line? One line. Only then write new code. No unrequested abstractions. No boilerplate for later. Deletion over addition.
+
+Surgical changes. Keep diffs narrow. No opportunistic reformats. No renames unless the task requires it. Only remove what your change made unused.
+
+Fail loud. No empty catch blocks. No silent retries. No returning fake success on real failure. Error messages must be actionable and specific.
+
+Security. Validate input at the boundary. Keep secrets out of code and logs. Apply least privilege. Flag immediately: SQL injection, XSS, command injection, path traversal, broken auth, leaked secrets.
+```
+
+---
+
+## Last verified: 2026-07-01

package/templates/docs/platform-setup/bolt.md

@@ -0,0 +1,22 @@
+# Bolt.new — goodvibes setup
+
+Bolt.new does not read project files for AI rules. You activate ponytail discipline by pasting the rules into the chat as a one-time instruction.
+
+## One-time setup
+
+1. Open your Bolt.new project.
+2. In the chat, paste: "Please follow these engineering rules for all code you write:" then copy the text from `CLAUDE.md` between `<!-- goodvibes:start -->` and `<!-- goodvibes:end -->`.
+3. Bolt.new will acknowledge and apply the rules for the rest of the session.
+4. Repeat this at the start of each new session, or save it as a pinned message if Bolt.new supports it.
+
+## Ponytail on Bolt.new
+
+Once the rules are in the chat context, Bolt.new follows the ponytail minimalism rules: minimal code, surgical changes, fail loud. The AI will tell you when it is skipping something that is not needed yet.
+
+## Headroom
+
+Headroom is not applicable inside Bolt.new — context is managed by the Bolt.new platform itself.
+
+---
+
+## Last verified: 2026-07-01

package/templates/docs/platform-setup/chatgpt.md

@@ -0,0 +1,38 @@
+# ChatGPT Projects — goodvibes setup
+
+ChatGPT does not read files from your project. Instead, you paste your rules directly into the project's custom instructions, and ChatGPT applies them to every conversation in that project.
+
+## Steps
+
+1. Go to [chatgpt.com](https://chatgpt.com) and sign in.
+2. Click **Projects** in the left sidebar. Create a new project or open an existing one.
+3. Click the project name at the top of the page. A panel opens on the right.
+4. Click **Project Instructions**.
+5. Paste the text below into the box.
+6. Click **Save**.
+
+That is it. From now on, every conversation in this project follows the goodvibes engineering rules.
+
+> If the steps above do not match what you see, look for **Project Instructions** or **Custom Instructions** in the project settings panel. The UI may change — the paste text stays the same.
+
+---
+
+## Paste this text
+
+```
+Engineering Rules — goodvibes
+
+Think before coding. State assumptions before implementing. Stop if an assumption is security-sensitive, schema-sensitive, or has multiple materially different interpretations.
+
+Simplicity first. Stop at the first option that works: Does this need to exist at all? Already in the codebase? Use it. Stdlib covers it? Use it. Can it be one line? One line. Only then write new code. No unrequested abstractions. No boilerplate for later. Deletion over addition.
+
+Surgical changes. Keep diffs narrow. No opportunistic reformats. No renames unless the task requires it. Only remove what your change made unused.
+
+Fail loud. No empty catch blocks. No silent retries. No returning fake success on real failure. Error messages must be actionable and specific.
+
+Security. Validate input at the boundary. Keep secrets out of code and logs. Apply least privilege. Flag immediately: SQL injection, XSS, command injection, path traversal, broken auth, leaked secrets.
+```
+
+---
+
+## Last verified: 2026-07-01

package/templates/docs/platform-setup/cursor.md

@@ -0,0 +1,23 @@
+# Cursor — goodvibes setup
+
+goodvibes init wrote `.cursor/rules/goodvibes.mdc` into your project. This file activates the ponytail minimalism rules automatically when you open the project in Cursor.
+
+## Ponytail is already active
+
+The rules enforce simplicity-first coding, fail-loud error handling, and surgical changes — no file you did not touch, no code you did not need. You do not need to paste anything. The rules are in `.cursor/rules/goodvibes.mdc` and Cursor loads them for every AI chat in this project.
+
+## Verify activation
+
+Open Cursor. In the AI chat, ask: "What are your active rules?" You should see a reference to goodvibes or ponytail in the response.
+
+## If you use .cursorrules (legacy)
+
+If your project has a `.cursorrules` file from before goodvibes, the `.cursor/rules/goodvibes.mdc` file is independent. Both will apply. You may want to merge them to avoid duplication.
+
+## Headroom (context compression)
+
+Cursor does not use Claude Code's MCP protocol. If you want context compression, install headroom separately and use it via its CLI. See [headroom docs](https://headroom-docs.vercel.app/).
+
+---
+
+## Last verified: 2026-07-01

package/templates/docs/platform-setup/kiro.md

@@ -0,0 +1,19 @@
+# Kiro — goodvibes setup
+
+goodvibes init wrote `.kiro/steering/goodvibes.md` into your project. Kiro applies steering files automatically to all AI interactions in the project.
+
+## Ponytail is already active
+
+The ponytail rules in `.kiro/steering/goodvibes.md` enforce simplicity-first coding, fail-loud error handling, and surgical changes. You do not need to paste anything or configure anything — the steering file is active as soon as you open the project in Kiro.
+
+## Verify activation
+
+Open Kiro and check the steering files panel in your project settings. You should see `goodvibes.md` listed as an always-on steering file.
+
+## Headroom (context compression)
+
+Kiro does not use Claude Code's MCP protocol. If you want context compression, install headroom separately and use it via its CLI. See [headroom docs](https://headroom-docs.vercel.app/).
+
+---
+
+## Last verified: 2026-07-01

package/templates/docs/platform-setup/replit.md

@@ -0,0 +1,26 @@
+# Replit Agent — goodvibes setup
+
+Replit Agent does not read files from your project automatically. Instead, you provide the rules as a system prompt for the Agent.
+
+## One-time setup
+
+1. Open your Repl.
+2. Find **System prompt** or **AI instructions** in the Agent settings panel.
+3. Copy the text from `CLAUDE.md` — specifically the section between `<!-- goodvibes:start -->` and `<!-- goodvibes:end -->`.
+4. Paste into the system prompt field and click **Save**.
+
+That is it. Replit Agent will follow the goodvibes rules for every task in this project.
+
+> If you do not see a system prompt field, look for **Agent instructions** or **Custom rules** in the project settings.
+
+## Ponytail on Replit
+
+Once the system prompt is set, Replit Agent follows the ponytail rules for every task: minimal code, no over-engineering, and explicit error handling. The AI will tell you if it is skipping something because it is not needed yet.
+
+## Headroom
+
+Replit manages its own context. Headroom is not applicable inside Replit — skip the headroom install step if you are Replit-only.
+
+---
+
+## Last verified: 2026-07-01

package/templates/docs/platform-setup/windsurf.md

@@ -0,0 +1,19 @@
+# Windsurf — goodvibes setup
+
+goodvibes init wrote `.windsurfrules` into your project. Windsurf reads this file automatically and applies the goodvibes engineering rules to every AI interaction.
+
+## Ponytail is already active
+
+The rules in `.windsurfrules` enforce simplicity-first coding, fail-loud error handling, and surgical changes. You do not need to paste anything — Windsurf picks up the file on its own.
+
+## Verify activation
+
+Open Windsurf. In the Cascade AI panel, ask: "What are your active rules?" You should see a reference to goodvibes or ponytail in the response.
+
+## Headroom (context compression)
+
+Windsurf does not use Claude Code's MCP protocol. If you want context compression, install headroom separately and use it via its CLI. See [headroom docs](https://headroom-docs.vercel.app/).
+
+---
+
+## Last verified: 2026-07-01

package/templates/replit.md

@@ -0,0 +1,32 @@
+# Engineering Rules — goodvibes
+<!-- Replit Agent may regenerate this file. Commit it to git to preserve your edits. -->
+
+## Project Overview
+This project uses goodvibes engineering rules. Apply them to every task.
+
+## Coding Style
+State assumptions before implementing. Stop if an assumption is security-sensitive, schema-sensitive, or has multiple materially different interpretations.
+
+## Simplicity First
+Stop at the first rung that holds:
+
+1. Does this need to exist at all? Speculative need → skip it. (YAGNI)
+2. Already in this codebase? Reuse it.
+3. Stdlib does it? Use it.
+4. Native platform feature covers it? Use it.
+5. Already-installed dependency solves it? Use it.
+6. Can it be one line? One line.
+7. Only then: the minimum code that works.
+
+No unrequested abstractions. No boilerplate for later. Deletion over addition.
+
+## Surgical Changes
+Keep diffs narrow. No opportunistic reformats. Only remove what your change made unused.
+
+## Fail Loud
+No empty catch blocks. No silent retries. No fake success on real failure. Error messages must be actionable.
+
+## Security
+Validate input at the boundary. Keep secrets out of code and logs. Apply least privilege.
+
+Flag immediately: SQL injection, XSS, command injection, path traversal, broken auth, leaked secrets.