bunosh 0.5.6 → 0.5.9

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:
@@ -423,6 +448,8 @@ export async function checkServices() {
 }
 ```
 
+`task.try` fully isolates failures from the exit code. Any `shell`, `fetch`, `task`, or `assert` that fails inside the callback is recorded as a warning (yellow), never as a failed task — so the run still exits with code `0` if the rest succeeded. `task.stopOnFailures()` is also suppressed inside `task.try`: an inner failure will never call `process.exit(1)`. The return value (`true`/`false`) is the only signal you act on.
+
 ## Documentation
 
 - **[Examples](docs/examples.md)** — Real-world examples and workflows

package/index.js

@@ -5,10 +5,11 @@ 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) {
@@ -26,6 +27,7 @@ global.bunosh = {
   writeToFile,
   copyFile,
   ai,
+  assert,
   stopOnFail,
   ignoreFail,
   task,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bunosh",
-  "version": "0.5.6",
+  "version": "0.5.9",
   "description": "Task runner that turns JavaScript functions into CLI commands. Runs on Bun and Node.js.",
   "type": "module",
   "module": "index.js",

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;
 }
@@ -83,10 +99,21 @@ export function getTaskPrefix(taskId) {
 
 export function createTaskInfo(name, parentId = null, isSilent = false) {
   const taskInfo = new TaskInfo(name, Date.now(), TaskStatus.RUNNING, parentId, isSilent);
+
+  let p = parentId;
+  while (p) {
+    const parent = runningTasks.get(p);
+    if (!parent) break;
+    if (parent.isTry || parent.isInsideTry) {
+      taskInfo.isInsideTry = true;
+      break;
+    }
+    p = parent.parentId;
+  }
+
   runningTasks.set(taskInfo.id, taskInfo);
   tasksExecuted.push(taskInfo);
 
-  // Also add to global array for exit handler
   if (globalThis._bunoshGlobalTasksExecuted) {
     globalThis._bunoshGlobalTasksExecuted.push(taskInfo);
   }
@@ -98,10 +125,19 @@ export function finishTaskInfo(taskInfo, success = true, error = null, output =
   const endTime = Date.now();
   const duration = endTime - taskInfo.startTime;
 
-  taskInfo.status = success ? TaskStatus.SUCCESS : TaskStatus.FAIL;
+  let status;
+  if (success) {
+    status = TaskStatus.SUCCESS;
+  } else if (taskInfo.isInsideTry) {
+    status = TaskStatus.WARNING;
+  } else {
+    status = TaskStatus.FAIL;
+  }
+
+  taskInfo.status = status;
   taskInfo.duration = duration;
   taskInfo.result = {
-    status: success ? TaskStatus.SUCCESS : TaskStatus.FAIL,
+    status,
     output: error?.message || output || null
   };
 
@@ -116,6 +152,8 @@ export class TaskInfo {
     this.status = status;
     this.parentId = parentId;
     this.isSilent = isSilent;
+    this.isTry = false;
+    this.isInsideTry = false;
   }
 }
 
@@ -125,55 +163,60 @@ export async function tryTask(name, fn, isSilent = true) {
     name = fn.toString().slice(0, 50).replace(/\s+/g, ' ').trim();
   }
 
-  const taskInfo = createTaskInfo(name, null, isSilent);
+  const taskInfo = createTaskInfo(name, getCurrentTaskId() || null, isSilent);
+  taskInfo.isTry = true;
+  const startIndex = tasksExecuted.length;
 
   const shouldPrint = !globalSilenceMode && !isSilent;
   const printer = new Printer('task', taskInfo.id);
   if (shouldPrint) printer.start(name);
 
+  let result;
+  let caughtError = null;
   try {
-    const result = await asyncLocalStorage.run(taskInfo.id, async () => {
+    result = await asyncLocalStorage.run(taskInfo.id, async () => {
       return await Promise.resolve(fn());
     });
+  } catch (err) {
+    caughtError = err;
+  }
 
-    const endTime = Date.now();
-    const duration = endTime - taskInfo.startTime;
+  const endTime = Date.now();
+  const duration = endTime - taskInfo.startTime;
 
-    // Check if result is a TaskResult and if it has failed
-    if (result && typeof result === 'object' && result.constructor && result.constructor.name === 'TaskResult') {
-      if (result.hasFailed || result.hasWarning) {
-        taskInfo.status = TaskStatus.WARNING;
-        taskInfo.duration = duration;
-        taskInfo.result = { status: TaskStatus.WARNING, output: result.output };
+  let failed = caughtError !== null;
 
-        if (shouldPrint) printer.warning(name);
-        runningTasks.delete(taskInfo.id);
+  if (!failed && result && typeof result === 'object' && result.constructor && result.constructor.name === 'TaskResult') {
+    if (result.hasFailed || result.hasWarning) failed = true;
+  }
 
-        return false;
+  if (!failed) {
+    for (let i = startIndex; i < tasksExecuted.length; i++) {
+      const t = tasksExecuted[i];
+      if (t === taskInfo) continue;
+      const s = t.result?.status;
+      if (s === TaskStatus.FAIL || s === TaskStatus.WARNING) {
+        failed = true;
+        break;
       }
     }
+  }
 
-    taskInfo.status = TaskStatus.SUCCESS;
-    taskInfo.duration = duration;
-    taskInfo.result = { status: TaskStatus.SUCCESS, output: result };
-
-    if (shouldPrint) printer.finish(name);
-    runningTasks.delete(taskInfo.id);
-
-    return true;
-  } catch (err) {
-    const endTime = Date.now();
-    const duration = endTime - taskInfo.startTime;
-
+  if (failed) {
     taskInfo.status = TaskStatus.WARNING;
     taskInfo.duration = duration;
-    taskInfo.result = { status: TaskStatus.WARNING, output: err.message };
-
-    if (shouldPrint) printer.warning(name, err);
+    taskInfo.result = { status: TaskStatus.WARNING, output: caughtError?.message || result?.output || null };
+    if (shouldPrint) printer.warning(name, caughtError);
     runningTasks.delete(taskInfo.id);
-
     return false;
   }
+
+  taskInfo.status = TaskStatus.SUCCESS;
+  taskInfo.duration = duration;
+  taskInfo.result = { status: TaskStatus.SUCCESS, output: result };
+  if (shouldPrint) printer.finish(name);
+  runningTasks.delete(taskInfo.id);
+  return true;
 }
 
 export async function task(name, fn, isSilent = false) {
@@ -182,7 +225,7 @@ export async function task(name, fn, isSilent = false) {
     name = fn.toString().slice(0, 50).replace(/\s+/g, ' ').trim();
   }
 
-  const taskInfo = createTaskInfo(name, null, isSilent);
+  const taskInfo = createTaskInfo(name, getCurrentTaskId() || null, isSilent);
 
   const shouldPrint = !globalSilenceMode && !isSilent;
   const printer = new Printer('task', taskInfo.id);
@@ -215,6 +258,15 @@ export async function task(name, fn, isSilent = false) {
     const endTime = Date.now();
     const duration = endTime - taskInfo.startTime;
 
+    if (taskInfo.isInsideTry) {
+      taskInfo.status = TaskStatus.WARNING;
+      taskInfo.duration = duration;
+      taskInfo.result = { status: TaskStatus.WARNING, output: err.message };
+      printer.warning(name, err);
+      runningTasks.delete(taskInfo.id);
+      return TaskResult.fail(err.message, { taskType: 'task', error: err });
+    }
+
     taskInfo.status = TaskStatus.FAIL;
     taskInfo.duration = duration;
     taskInfo.result = { status: TaskStatus.FAIL, output: err.message };
@@ -222,28 +274,16 @@ 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);
     }
-    
+
     return TaskResult.fail(err.message, { taskType: 'task', error: err });
   }
 }

package/src/tasks/assert.js

@@ -0,0 +1,30 @@
+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);
+
+  if (taskInfo.isInsideTry) {
+    printer.warning(message, error);
+    finishTaskInfo(taskInfo, false, error, message);
+    return;
+  }
+
+  printer.error(message, error);
+  finishTaskInfo(taskInfo, false, error, message);
+
+  if (isStopOnFailuresMode() && !isTestEnv()) process.exit(1);
+}

package/types.d.ts

@@ -34,8 +34,9 @@ declare global {
         copyFile(src: string, dst: string): void;
         stopOnFail(enable?: boolean): void;
         ignoreFail(enable?: boolean): void;
-        buildCmd(cmd: string): (args: string) => Promise<any>;       
+        buildCmd(cmd: string): (args: string) => Promise<any>;
         task(name: string | Function, fn?: Function): Promise<any>;
+        assert(condition: any, message?: string): asserts condition;
       };
     }
   }