bunosh 0.5.0 → 0.5.8

package/README.md

@@ -187,7 +187,7 @@ Bunoshfile.api.js    # bunosh api:deploy, bunosh api:test
 Built-in tasks are available via `global.bunosh`:
 
 ```javascript
-const { exec, shell, fetch, writeToFile, copyFile, task } = global.bunosh;
+const { exec, shell, fetch, writeToFile, copyFile, task, assert } = global.bunosh;
 ```
 
 > Global variables are used instead of imports so bunosh works with the single-executable on any platform.
@@ -195,6 +195,7 @@ const { exec, shell, fetch, writeToFile, copyFile, task } = global.bunosh;
 * Async tasks: `exec`, `shell`, `fetch`
 * Sync tasks: `writeToFile`, `copyFile`
 * Task wrapper: `task`
+* Precondition guard: `assert`
 
 Each task returns a `TaskResult` object:
 
@@ -273,6 +274,30 @@ For details see the [Bun shell](https://bun.sh/docs/runtime/shell) reference.
 | `exec` | Single command execution | spawn process | Node.js + Bun, platform dependent |
 | `shell` | Cross-platform shell commands | Bun shell | Bun only, cross-platform |
 
+### `assert`
+
+Guard a command on a precondition. If the condition is falsy, `assert` prints a red failure line and records a failed task — the run continues, and the process exits with code 1 at the end:
+
+```javascript
+export async function deploy() {
+  assert(process.env.TOKEN, 'TOKEN must be set');
+  assert(await Bun.file('dist/bundle.js').exists(), 'bundle not built');
+  await shell`./scripts/deploy.sh`;
+}
+```
+
+With `task.stopOnFailures()` enabled, a failed `assert` exits immediately at that line:
+
+```javascript
+export async function strict() {
+  task.stopOnFailures();
+  assert(process.env.TOKEN, 'TOKEN must be set');
+  await shell`./scripts/deploy.sh`;
+}
+```
+
+`assert` does not throw a JavaScript exception in default mode — it records the failure and execution continues. Use `task.stopOnFailures()` (or `return` after the `assert`) when you need a hard stop.
+
 ### `fetch`
 
 Wraps the fetch API as a task:
@@ -427,7 +452,6 @@ export async function checkServices() {
 
 - **[Examples](docs/examples.md)** — Real-world examples and workflows
 - **[AI Integration](docs/ai.md)** — Built-in AI support
-- **[MCP Integration](docs/mcp.md)** — Expose commands to AI assistants (Claude, Cursor, etc.)
 - **[JavaScript Execution](docs/javascript-execution.md)** — Execute JavaScript directly via CLI
 - **[Bash Migration Guide](docs/bash-migration-guide.md)** — Convert bash scripts to Bunosh
 - **[Node.js Migration Guide](docs/nodejs-migration-guide.md)** — Migrate from Node.js scripts

package/bunosh.js

@@ -124,45 +124,6 @@ async function main() {
     process.argv.splice(envFileIndex, 1);
   }
 
-  const mcpFlagIndex = process.argv.indexOf('-mcp');
-  if (mcpFlagIndex !== -1) {
-    process.argv.splice(mcpFlagIndex, 1);
-
-    process.env.BUNOSH_MCP_MODE = 'true';
-
-    const { createMcpServer, startMcpServer } = await import('./src/mcp-server.js');
-
-    let tasksFile;
-    let bunoshfileDir;
-    if (customBunoshfile) {
-      const resolvedPath = path.isAbsolute(customBunoshfile) ? customBunoshfile : path.resolve(customBunoshfile);
-      if (existsSync(resolvedPath) && statSync(resolvedPath).isDirectory()) {
-        tasksFile = path.join(resolvedPath, BUNOSHFILE);
-        bunoshfileDir = resolvedPath;
-      } else {
-        tasksFile = resolvedPath;
-        bunoshfileDir = path.dirname(resolvedPath);
-      }
-    } else {
-      tasksFile = path.join(process.cwd(), BUNOSHFILE);
-      bunoshfileDir = process.cwd();
-    }
-
-    if (!existsSync(tasksFile)) {
-      console.error('Bunoshfile not found for MCP mode');
-      process.exit(1);
-    }
-
-    loadEnvFiles(bunoshfileDir, customEnvFile);
-
-    const { tasks, sources } = await loadBunoshfiles(tasksFile);
-
-    const server = createMcpServer(tasks, sources);
-    await startMcpServer(server);
-
-    return;
-  }
-
   let tasksFile;
   let bunoshfileDir;
   if (customBunoshfile) {

package/index.js

@@ -1,17 +1,19 @@
-import exec from "./src/tasks/exec.js";
 import shell from "./src/tasks/shell.js";
+// Deprecated: `exec` is an alias for `shell`, kept for backward compatibility.
+const exec = shell;
 import fetch from "./src/tasks/fetch.js";
 import writeToFile from "./src/tasks/writeToFile.js";
 import copyFile from "./src/tasks/copyFile.js";
 import ai from "./src/tasks/ai.js";
+import assert from "./src/tasks/assert.js";
 import { ask, yell, say } from "./src/io.js";
 import { task, tryTask, stopOnFail, ignoreFail, stopOnFailures, ignoreFailures, silence, prints, silent, TaskResult } from "./src/task.js";
 
-export { exec, shell, fetch, writeToFile, copyFile, ai, ask, yell, say, task, tryTask, stopOnFail, ignoreFail, stopOnFailures, ignoreFailures, silence, prints, silent, TaskResult };
+export { exec, shell, fetch, writeToFile, copyFile, ai, assert, ask, yell, say, task, tryTask, stopOnFail, ignoreFail, stopOnFailures, ignoreFailures, silence, prints, silent, TaskResult };
 
 export function buildCmd(cmd) {
   return function (args) {
-    return exec`${cmd} ${args}`;
+    return shell`${cmd} ${args}`;
   };
 }
 
@@ -25,6 +27,7 @@ global.bunosh = {
   writeToFile,
   copyFile,
   ai,
+  assert,
   stopOnFail,
   ignoreFail,
   task,
@@ -35,7 +38,7 @@ global.bunosh = {
   silent,
   TaskResult,
   buildCmd,
-  $: exec,
+  $: shell,
 };
 
 export default global.bunosh;

package/package.json

@@ -1,8 +1,25 @@
 {
   "name": "bunosh",
-  "version": "0.5.0",
+  "version": "0.5.8",
+  "description": "Task runner that turns JavaScript functions into CLI commands. Runs on Bun and Node.js.",
   "type": "module",
   "module": "index.js",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DavertMik/bunosh.git"
+  },
+  "homepage": "https://github.com/DavertMik/bunosh#readme",
+  "bugs": {
+    "url": "https://github.com/DavertMik/bunosh/issues"
+  },
+  "author": "davert",
+  "keywords": [
+    "task-runner",
+    "cli",
+    "bun",
+    "automation",
+    "scripts"
+  ],
   "bin": {
     "bunosh": "./bunosh.js"
   },
@@ -19,7 +36,6 @@
     "@ai-sdk/openai": "^2.0.23",
     "@babel/parser": "^7.27.5",
     "@babel/traverse": "^7.27.4",
-    "@modelcontextprotocol/sdk": "^1.19.1",
     "ai": "^5.0.29",
     "chalk": "^5.4.1",
     "commander": "^14.0.0",

package/src/formatters/console.js

@@ -12,7 +12,11 @@ const STATUS_CONFIG = {
 
 export class ConsoleFormatter extends BaseFormatter {
   shouldDelayStart() {
-    return false;
+    return true;
+  }
+
+  getStartDelay() {
+    return 1000;
   }
   format(taskName, status, taskType, extra = {}) {
     const config = STATUS_CONFIG[status];

package/src/io.js

@@ -7,11 +7,6 @@ export function say(...args) {
 }
 
 export async function ask(question, defaultValueOrOptions = {}, options = {}) {
-  // Check if we're in MCP mode and should use the interactive ask function
-  if (globalThis._mcpAskFunction) {
-    return globalThis._mcpAskFunction(question, defaultValueOrOptions, options);
-  }
-
   // Track that we're in an ask operation to prevent duplicate exit summaries
   globalThis._bunoshInAskOperation = true;
   // Smart parameter detection

package/src/printer.js

@@ -85,7 +85,10 @@ export class Printer {
     const delay = this.formatter.getStartDelay ? this.formatter.getStartDelay() : 50;
 
     if (this.formatter.shouldDelayStart && this.formatter.shouldDelayStart()) {
+      this.pendingStart = { taskName, extra };
       this.startTimeout = setTimeout(() => {
+        this.startTimeout = null;
+        this.pendingStart = null;
         this.hasStarted = true;
         this.print(taskName, 'start', extra);
       }, delay);
@@ -95,19 +98,37 @@ export class Printer {
     }
   }
 
-  finish(taskName, extra = {}) {
+  _flushPendingStart() {
+    if (!this.startTimeout) return;
+    clearTimeout(this.startTimeout);
+    this.startTimeout = null;
+    const pending = this.pendingStart;
+    this.pendingStart = null;
+    if (pending) {
+      this.hasStarted = true;
+      this.print(pending.taskName, 'start', pending.extra);
+    }
+  }
+
+  _cancelPendingStart() {
     if (this.startTimeout) {
       clearTimeout(this.startTimeout);
       this.startTimeout = null;
     }
+    this.pendingStart = null;
+  }
+
+  cancel() {
+    this._cancelPendingStart();
+  }
+
+  finish(taskName, extra = {}) {
+    this._cancelPendingStart();
     this.print(taskName, 'finish', extra);
   }
 
   error(taskName, error = null, extra = {}) {
-    if (this.startTimeout) {
-      clearTimeout(this.startTimeout);
-      this.startTimeout = null;
-    }
+    this._cancelPendingStart();
     if (error) {
       extra.error = typeof error === 'string' ? error : error.message;
     }
@@ -115,10 +136,7 @@ export class Printer {
   }
 
   warning(taskName, error = null, extra = {}) {
-    if (this.startTimeout) {
-      clearTimeout(this.startTimeout);
-      this.startTimeout = null;
-    }
+    this._cancelPendingStart();
     if (error) {
       extra.error = typeof error === 'string' ? error : error.message;
     }
@@ -128,6 +146,8 @@ export class Printer {
   output(line, isError = false) {
     if (!line.trim()) return;
 
+    this._flushPendingStart();
+
     // Add task prefix for parallel tasks on output lines
     const prefix = this.taskId ? getTaskPrefix(this.taskId) : '';
     const prefixedLine = prefix ? `${prefix} ${line}` : line;

package/src/program.js

@@ -8,7 +8,7 @@ import { yell } from './io.js';
 import { formatError } from './error-formatter.js';
 import cprint from "./font.js";
 import { handleCompletion, detectCurrentShell, installCompletion, getCompletionPaths } from './completion.js';
-import { upgradeCommand } from './upgrade.js';
+import { upgradeCommand, printUpgradeNoticeIfAvailable } from './upgrade.js';
 
 export const BUNOSHFILE = `Bunoshfile.js`;
 
@@ -265,16 +265,22 @@ export default async function bunosh(commands, sources) {
         }
       });
 
-      const optionsObj = commanderArgs[commanderArgs.length - 1];
-      if (optionsObj && typeof optionsObj === 'object') {
-        Object.keys(opts).forEach((optName) => {
-          const dasherizedOpt = optName.replace(/([A-Z])/g, '-$1').toLowerCase();
-          if (optionsObj[dasherizedOpt] !== undefined) {
-            transformedArgs.push(optionsObj[dasherizedOpt]);
+      const optNames = Object.keys(opts);
+      if (optNames.length > 0) {
+        const lastArg = commanderArgs[commanderArgs.length - 1];
+        const optionsObj = (lastArg && typeof lastArg.opts === 'function') ? lastArg.opts() : lastArg;
+        const mergedOpts = {};
+        optNames.forEach((optName) => {
+          const camelName = optName.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+          if (optionsObj && optionsObj[camelName] !== undefined) {
+            mergedOpts[camelName] = optionsObj[camelName];
+          } else if (optionsObj && optionsObj[optName] !== undefined) {
+            mergedOpts[camelName] = optionsObj[optName];
           } else {
-            transformedArgs.push(opts[optName]);
+            mergedOpts[camelName] = opts[optName];
           }
         });
+        transformedArgs.push(mergedOpts);
       }
 
       try {
@@ -385,6 +391,23 @@ export default async function bunosh(commands, sources) {
 
   internalCommands.push(setupCompletionCmd);
 
+  const SKILLS_REPO = 'DavertMik/bunosh-skills';
+
+  const installSkillsCmd = program.command('install-skills')
+    .description('Print the command to install Bunosh AI agent skills.')
+    .action(() => {
+      console.log();
+      console.log(`🤖 Install Bunosh AI agent skills (Claude Code, Cursor, Codex, ...):`);
+      console.log();
+      console.log(`   ${color.bold(`npx skills add ${SKILLS_REPO}`)}`);
+      console.log();
+      console.log(color.dim(`   Skills: bunosh-fundamentals, migrate-to-bunosh`));
+      console.log(color.dim(`   ${SKILLS_REPO} · https://buno.sh`));
+      console.log();
+    });
+
+  internalCommands.push(installSkillsCmd);
+
   const upgradeCmd = program.command('upgrade')
     .description('Upgrade bunosh to the latest version')
     .option('-f, --force', 'Force upgrade even if already on latest version')
@@ -410,7 +433,7 @@ export default async function bunosh(commands, sources) {
       }
 
       const lines = description.split('\n');
-      const firstLine = `  ${color.white.bold(paddedName)} ${lines[0]}`;
+      const firstLine = `  ${color.white.bold(paddedName)} ${color.dim(lines[0])}`;
       const indentedLines = lines.slice(1).map(line =>
         line.trim() ? `                          ${line}` : ''
       ).filter(line => line);
@@ -445,7 +468,7 @@ ${mainCommands}
       }
 
       const lines = description.split('\n');
-      const firstLine = `  ${color.white.bold(paddedName)} ${lines[0]}`;
+      const firstLine = `  ${color.white.bold(paddedName)} ${color.dim(lines[0])}`;
       const indentedLines = lines.slice(1).map(line =>
         line.trim() ? `                          ${line}` : ''
       ).filter(line => line);
@@ -471,7 +494,7 @@ ${devCommands}
         }
 
         const lines = description.split('\n');
-        const firstLine = `  ${color.white.bold(paddedName)} ${lines[0]}`;
+        const firstLine = `  ${color.white.bold(paddedName)} ${color.dim(lines[0])}`;
         const indentedLines = lines.slice(1).map(line =>
           line.trim() ? `                          ${line}` : ''
         ).filter(line => line);
@@ -485,7 +508,10 @@ ${namespaceCommands}
     }
   });
 
-  helpText += color.dim(`Special Commands:
+  const helpFlagRequested = process.argv.includes('--help') || process.argv.includes('-h');
+
+  if (helpFlagRequested) {
+    helpText += color.dim(`Special Commands:
   ${color.bold('bunosh edit')}           📝 Edit bunosh file with $EDITOR
   ${color.bold('bunosh export:scripts')} 📥 Export commands to package.json
   ${color.bold('bunosh upgrade')}        🦾 Upgrade bunosh
@@ -494,6 +520,13 @@ ${namespaceCommands}
   ${color.bold('bunosh --env-file …')}   🔧 Load custom environment file
 `);
 
+    helpText += `
+${color.bold('🤖 AI agent skills')} ${color.dim('(Claude Code, Cursor, Codex, ...)')}
+  ${color.bold('npx skills add DavertMik/bunosh-skills')}
+  ${color.dim('bunosh-fundamentals · migrate-to-bunosh — see "bunosh install-skills"')}
+`;
+  }
+
   program.addHelpText('after', helpText);
 
   program.on("command:*", (cmd) => {
@@ -505,6 +538,7 @@ ${namespaceCommands}
 
   if (process.argv.length === 2) {
     program.outputHelp();
+    await printUpgradeNoticeIfAvailable();
     return program;
   }
 

package/src/task.js

@@ -47,6 +47,22 @@ export function getIgnoreFailuresMode() {
   return ignoreFailuresMode;
 }
 
+export function isStopOnFailuresMode() {
+  return stopOnFailuresMode;
+}
+
+export function isTestEnv() {
+  const commandArgs = process.argv.slice(2);
+  return process.env.NODE_ENV === 'test' ||
+    commandArgs.some(arg => {
+      const lower = arg.toLowerCase();
+      return lower.includes('vitest') ||
+             lower.includes('jest') ||
+             lower === '--test' ||
+             lower.startsWith('test:');
+    });
+}
+
 export function silence() {
   globalSilenceMode = true;
 }
@@ -198,6 +214,8 @@ export async function task(name, fn, isSilent = false) {
 
     // Check if result is a TaskResult instance
     if (result && result.constructor && result.constructor.name === 'TaskResult') {
+      printer.cancel();
+      runningTasks.delete(taskInfo.id);
       return result;
     }
 
@@ -220,24 +238,12 @@ export async function task(name, fn, isSilent = false) {
     printer.error(name, err);
     runningTasks.delete(taskInfo.id);
 
-    // Don't exit during testing
-    const commandArgs = process.argv.slice(2);
-    const isTestEnvironment = process.env.NODE_ENV === 'test' ||
-                              typeof Bun?.jest !== 'undefined' ||
-                              commandArgs.some(arg => {
-                                const lowerArg = arg.toLowerCase();
-                                return lowerArg.includes('vitest') ||
-                                       lowerArg.includes('jest') ||
-                                       lowerArg === '--test' ||
-                                       lowerArg.startsWith('test:');
-                              });
-
-    // Exit immediately if stopOnFailures mode is enabled
+    const isTestEnvironment = isTestEnv();
+
     if (stopOnFailuresMode && !isTestEnvironment) {
       process.exit(1);
     }
-    
-    // Also exit if stopFailToggle is enabled (legacy behavior)
+
     if (stopFailToggle && !isTestEnvironment) {
       process.exit(1);
     }
@@ -246,8 +252,13 @@ export async function task(name, fn, isSilent = false) {
   }
 }
 
-// Add try method to task function
+// Add methods to task function
 task.try = tryTask;
+task.stopOnFailures = stopOnFailures;
+task.ignoreFailures = ignoreFailures;
+task.silence = silence;
+task.prints = prints;
+task.silent = silent;
 
 
 export class SilentTaskWrapper {

package/src/tasks/assert.js

@@ -0,0 +1,23 @@
+import { createTaskInfo, finishTaskInfo, getCurrentTaskId, runningTasks, isStopOnFailuresMode, isTestEnv } from '../task.js';
+import Printer from '../printer.js';
+
+export default function assert(condition, message = 'Assertion failed') {
+  const currentTaskId = getCurrentTaskId();
+  const parent = currentTaskId ? runningTasks.get(currentTaskId) : null;
+  const isParentSilent = parent?.isSilent || false;
+
+  const taskInfo = createTaskInfo(message, currentTaskId, isParentSilent);
+  const printer = new Printer('assert', taskInfo.id);
+
+  if (condition) {
+    printer.finish(message);
+    finishTaskInfo(taskInfo, true, null, message);
+    return;
+  }
+
+  const error = new Error(message);
+  printer.error(message, error);
+  finishTaskInfo(taskInfo, false, error, message);
+
+  if (isStopOnFailuresMode() && !isTestEnv()) process.exit(1);
+}