v4.1.0

- Fixed bug where CLI with no args would return entire argv including node path
- Removed debug 'Wanted command: ...' log from startParse()

.smartconfig.json

@@ -1,9 +1,5 @@
 {
-  "npmci": {
-    "npmGlobalTools": [],
-    "npmAccesslevel": "public"
-  },
-  "gitzone": {
+  "@git.zone/cli": {
     "projectType": "npm",
     "module": {
       "githost": "code.foss.global",
@@ -12,23 +8,25 @@
       "description": "A library that simplifies building reactive command-line applications using observables, with robust support for commands, arguments, options, aliases, and asynchronous operation management.",
       "npmPackagename": "@push.rocks/smartcli",
       "license": "MIT",
-      "keywords": [
-        "CLI",
-        "command line",
-        "observable",
-        "reactive",
-        "asynchronous",
-        "commands",
-        "arguments",
-        "options",
-        "alias",
-        "typescript",
-        "node.js",
-        "development tool"
-      ]
+      "projectDomain": "push.rocks"
+    },
+    "release": {
+      "targets": {
+        "npm": {
+          "registries": [
+            "https://verdaccio.lossless.digital",
+            "https://registry.npmjs.org"
+          ],
+          "accessLevel": "public"
+        }
       }
     },
-  "tsdoc": {
-    "legal": "\n## License and Legal Information\n\nThis repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. \n\n**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.\n\n### Trademarks\n\nThis project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.\n\n### Company Information\n\nTask Venture Capital GmbH  \nRegistered at District court Bremen HRB 35230 HB, Germany\n\nFor any legal inquiries or if you require further information, please contact us via email at hello@task.vc.\n\nBy using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.\n"
+    "schemaVersion": 2
+  },
+  "@git.zone/tsdoc": {
+    "legal": "\n## License and Legal Information\n\nThis repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [LICENSE](LICENSE) file within this repository. \n\n**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.\n\n### Trademarks\n\nThis project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.\n\n### Company Information\n\nTask Venture Capital GmbH  \nRegistered at District court Bremen HRB 35230 HB, Germany\n\nFor any legal inquiries or if you require further information, please contact us via email at hello@task.vc.\n\nBy using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.\n"
+  },
+  "@ship.zone/szci": {
+    "npmGlobalTools": []
   }
 }

.vscode/settings.json

@@ -1,26 +0,0 @@
-{
-  "json.schemas": [
-    {
-      "fileMatch": ["/npmextra.json"],
-      "schema": {
-        "type": "object",
-        "properties": {
-          "npmci": {
-            "type": "object",
-            "description": "settings for npmci"
-          },
-          "gitzone": {
-            "type": "object",
-            "description": "settings for gitzone",
-            "properties": {
-              "projectType": {
-                "type": "string",
-                "enum": ["website", "element", "service", "npm", "wcc"]
-              }
-            }
-          }
-        }
-      }
-    }
-  ]
-}

LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2015 Push.Rocks
+Copyright (c) 2015 Task Venture Capital GmbH
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

changelog.md

@@ -1,5 +1,65 @@
 # Changelog
 
+## Pending
+
+
+## 2026-05-13 - 4.1.0
+
+### Features
+
+- add live terminal task rendering with interactive and non-interactive output modes (terminal)
+  - introduces SmartcliTerminal and SmartcliTerminalTask exports for fixed-row task rendering
+  - supports task updates, completion, failure handling, and persistent error output
+  - detects interactive terminals and falls back to append-only logs in CI or non-TTY environments
+  - adds tests covering interactive rendering, non-interactive logging, and error attachment behavior
+
+## 2026-04-30 - 4.0.21 - fix(smartcli)
+tighten command parsing and error handling while updating build and package configuration
+
+- throw an explicit error when triggering an unregistered command instead of failing on an undefined subject
+- make the cli version property optional to align with current typing expectations
+- update tests to use explicit argv input and export the tap startup call for runtime compatibility
+- enable stricter TypeScript configuration and refresh build, dependency, and package metadata files
+
+## 2025-10-28 - 4.0.19 - fix(license)
+Update license files and add local tool settings
+
+- Update LICENSE header to reference Task Venture Capital GmbH as copyright holder
+- Add a new license file containing the full MIT license text
+- Add .claude/settings.local.json to store local tool permission settings
+
+## 2025-10-28 - 4.0.18 - fix(smartcli)
+Allow passing argv to startParse and improve getUserArgs Deno/runtime handling; update tests and add license
+
+- Smartcli.startParse now accepts an optional testArgv parameter to bypass automatic runtime detection (makes testing deterministic).
+- getUserArgs logic refined: always prefer Deno.args when available (handles Deno run and compiled executables reliably) and improve execPath fallback and slicing behavior for Node/Bun/other launchers.
+- Tests updated: test/test.node+deno+bun.ts now passes process.argv explicitly to startParse to avoid Deno.args interference in test environments.
+- Added MIT LICENSE file and a local .claude/settings.local.json for environment/permission settings.
+
+## 2025-10-28 - 4.0.17 - fix(license)
+Add MIT license and local Claude settings
+
+- Add LICENSE file (MIT) to repository
+- Add .claude/settings.local.json with local permissions for tooling
+
+## 2025-10-28 - 4.0.16 - fix(smartcli.helpers)
+Improve CLI argument parsing and Deno runtime detection; use getUserArgs consistently
+
+- Enhance getUserArgs() to prefer Deno.args but detect when process.argv was manipulated (e.g. in tests) and fallback to manual parsing
+- Add robust handling of process.execPath / execPath basename and compute correct argv offset for known launchers vs. compiled executables
+- Call getUserArgs() (no explicit process.argv) from Smartcli.getOption and Smartcli.startParse to ensure consistent cross-runtime behavior
+- Expand readme.hints.md with detailed cross-runtime examples and explanation of Deno.args vs process.argv for compiled executables
+- Add local claude settings file for tooling configuration
+
+## 2025-10-28 - 4.0.15 - fix(smartcli.helpers)
+Add robust getUserArgs helper and refactor Smartcli to use it; add MIT license and update documentation
+
+- Add ts/smartcli.helpers.ts: getUserArgs to normalize user arguments across Node.js, Deno (run/compiled), and Bun, with safety checks for test environments
+- Refactor Smartcli (ts/smartcli.classes.smartcli.ts) to use getUserArgs in startParse and getOption for correct argument parsing and improved test compatibility
+- Update readme.hints.md with detailed cross-runtime CLI argument parsing guidance
+- Add LICENSE (MIT) file
+- Add .claude/settings.local.json (local settings)
+
 ## 2025-10-28 - 4.0.14 - fix(license)
 Add MIT license file
 

package.json

@@ -1,14 +1,14 @@
 {
   "name": "@push.rocks/smartcli",
   "private": false,
-  "version": "4.0.14",
+  "version": "4.1.0",
   "description": "A library that simplifies building reactive command-line applications using observables, with robust support for commands, arguments, options, aliases, and asynchronous operation management.",
   "main": "dist_ts/index.js",
   "typings": "dist_ts/index.d.ts",
   "type": "module",
   "scripts": {
     "test": "(tstest test/ --verbose)",
-    "build": "(tsbuild --web --allowimplicitany)",
+    "build": "tsbuild --web",
     "buildDocs": "tsdoc"
   },
   "repository": {
@@ -32,22 +32,23 @@
   "author": "Lossless GmbH <office@lossless.com> (https://lossless.com)",
   "license": "MIT",
   "bugs": {
-    "url": "https://gitlab.com/pushrocks/smartcli/issues"
+    "url": "https://code.foss.global/push.rocks/smartcli/issues"
   },
   "homepage": "https://code.foss.global/push.rocks/smartcli",
   "dependencies": {
-    "@push.rocks/lik": "^6.2.2",
-    "@push.rocks/smartlog": "^3.1.10",
+    "@push.rocks/lik": "^6.4.1",
+    "@push.rocks/smartlog": "^3.2.2",
     "@push.rocks/smartobject": "^1.0.12",
-    "@push.rocks/smartpromise": "^4.2.3",
+    "@push.rocks/smartpromise": "^4.2.4",
     "@push.rocks/smartrx": "^3.0.10",
     "yargs-parser": "22.0.0"
   },
   "devDependencies": {
-    "@git.zone/tsbuild": "^2.6.8",
-    "@git.zone/tsrun": "^1.6.2",
-    "@git.zone/tstest": "^2.7.0",
-    "@types/node": "^24.9.1"
+    "@git.zone/tsbuild": "^4.4.1",
+    "@git.zone/tsrun": "^2.0.4",
+    "@git.zone/tstest": "^3.6.6",
+    "@types/node": "^25.7.0",
+    "@types/yargs-parser": "^21.0.3"
   },
   "files": [
     "ts/**/*",
@@ -58,11 +59,12 @@
     "dist_ts_web/**/*",
     "assets/**/*",
     "cli.js",
-    "npmextra.json",
+    ".smartconfig.json",
+    "LICENSE",
     "readme.md"
   ],
   "browserslist": [
     "last 1 chrome versions"
   ],
-  "packageManager": "pnpm@10.18.1+sha512.77a884a165cbba2d8d1c19e3b4880eee6d2fcabd0d879121e282196b80042351d5eb3ca0935fa599da1dc51265cc68816ad2bddd2a2de5ea9fdf92adbec7cd34"
+  "packageManager": "pnpm@10.28.2"
 }

readme.hints.md

@@ -1 +1,42 @@
-No specific hints.
+## Cross-Runtime Compatibility
+
+### CLI Argument Parsing
+The module uses a robust cross-runtime approach for parsing command-line arguments through the `getUserArgs()` utility in `ts/smartcli.helpers.ts`.
+
+**Runtime-Specific Implementations:**
+
+| Runtime | process.argv Structure | Preferred API | Reason |
+|---------|------------------------|---------------|---------|
+| **Node.js** | `["/path/to/node", "/path/to/script.js", ...userArgs]` | Manual parsing | No native user-args API |
+| **Deno run** | `["deno", "/path/to/script.ts", ...userArgs]` | `Deno.args` ✅ | Pre-filtered by runtime |
+| **Deno compiled** | `["/path/to/binary", "/tmp/deno-compile-.../mod.ts", ...userArgs]` | `Deno.args` ✅ | Filters internal bundle path |
+| **Bun** | `["/path/to/bun", "/path/to/script.ts", ...userArgs]` | Manual parsing | Bun.argv not pre-filtered |
+
+**Why Deno.args is Critical for Compiled Executables:**
+
+Deno compiled executables insert an internal bundle path at `argv[1]`:
+```javascript
+process.argv = [
+  "/usr/local/bin/moxytool",              // argv[0] - executable
+  "/tmp/deno-compile-moxytool/mod.ts",    // argv[1] - INTERNAL bundle path
+  "scripts",                               // argv[2] - actual user command
+  "--option"                               // argv[3+] - user args
+]
+
+Deno.args = ["scripts", "--option"]  // ✓ Correctly filtered by Deno runtime
+```
+
+**getUserArgs() Logic:**
+
+1. **Prefer Deno.args** when available (unless process.argv appears manipulated for testing)
+2. **Fallback to manual parsing** for Node.js and Bun:
+   - Check `process.execPath` basename
+   - Known launchers (node, deno, bun, tsx, ts-node) → skip 2 args
+   - Unknown (compiled executables) → skip 1 arg
+3. **Test detection**: If `process.argv.length > 2` in Deno, use manual parsing (handles test manipulation)
+
+**Key Benefits:**
+- ✅ Works with custom-named compiled executables
+- ✅ Handles Deno's internal bundle path automatically
+- ✅ Compatible with test environments
+- ✅ No heuristics needed for Deno (runtime does the work)

test/test.node+deno+bun.ts

@@ -3,6 +3,25 @@ import * as smartrx from '@push.rocks/smartrx';
 
 import * as smartcli from '../ts/index.js';
 
+class TestWritable implements smartcli.ISmartcliWritable {
+  public chunks: string[] = [];
+  public isTTY: boolean;
+  public columns = 80;
+
+  constructor(isTTYArg: boolean) {
+    this.isTTY = isTTYArg;
+  }
+
+  public write(chunkArg: string): boolean {
+    this.chunks.push(chunkArg);
+    return true;
+  }
+
+  public toString(): string {
+    return this.chunks.join('');
+  }
+}
+
 tap.test('should create a new Smartcli', async () => {
   const smartCliTestObject = new smartcli.Smartcli();
   expect(smartCliTestObject).toBeInstanceOf(smartcli.Smartcli);
@@ -16,10 +35,7 @@ tap.test('should add an command', async (toolsArg) => {
   awesomeCommandSubject.subscribe(() => {
     done.resolve();
   });
-  console.log(process.argv);
-  process.argv.splice(2, 0, 'awesome');
-  console.log(process.argv);
-  smartCliTestObject.startParse();
+  smartCliTestObject.startParse(['node', 'test.js', 'awesome']);
   await done.promise;
 });
 
@@ -39,4 +55,64 @@ tap.test('should accept a command', async () => {
   expect(hasExecuted).toBeTrue();
 });
 
-tap.start();
+tap.test('should render terminal tasks in non-interactive mode', async () => {
+  const stream = new TestWritable(false);
+  const terminal = new smartcli.SmartcliTerminal({ stream, interactive: false, colors: false });
+  const task = terminal.createTask({ job: 'build package', rows: 2 });
+
+  task.update('running tsbuild');
+  task.complete('done');
+
+  const output = stream.toString();
+  expect(output).toInclude('[start] build package');
+  expect(output).toInclude('[build package] running tsbuild');
+  expect(output).toInclude('[ok] build package - done');
+  expect(terminal.getTasks()).toHaveLength(0);
+});
+
+tap.test('should render fixed rows in interactive mode', async () => {
+  const stream = new TestWritable(true);
+  const terminal = new smartcli.SmartcliTerminal({ stream, interactive: true, colors: false });
+  const task = terminal.createTask({ job: 'install dependencies', rows: 2 });
+
+  task.update('fetching packages');
+
+  const renderedRows = task.renderPlainRows(80);
+  expect(renderedRows).toHaveLength(2);
+  expect(renderedRows[0]).toInclude('[run] install dependencies');
+  expect(stream.toString()).toInclude('\u001B[2K');
+
+  task.complete('installed');
+
+  expect(stream.toString()).toInclude('[ok] install dependencies - installed');
+  expect(terminal.getTasks()).toHaveLength(0);
+});
+
+tap.test('should attach persistent terminal task errors', async () => {
+  const stream = new TestWritable(true);
+  const terminal = new smartcli.SmartcliTerminal({ stream, interactive: true, colors: false });
+  const task = terminal.createTask({ job: 'deploy release', rows: 3 });
+
+  task.attachError('deployment failed', { keepOpen: true });
+
+  expect(task.status).toEqual('failed');
+  expect(task.getErrorLines()).toContain('deployment failed');
+  expect(task.renderPlainRows(80)[0]).toInclude('[err] deploy release');
+  expect(terminal.getTasks()).toHaveLength(1);
+
+  terminal.clear();
+});
+
+tap.test('should collapse failed terminal tasks into permanent output', async () => {
+  const stream = new TestWritable(false);
+  const terminal = new smartcli.SmartcliTerminal({ stream, interactive: false, colors: false });
+  const task = terminal.createTask({ job: 'publish package' });
+
+  task.attachError('registry rejected package');
+
+  const output = stream.toString();
+  expect(output).toInclude('[err] publish package - registry rejected package');
+  expect(terminal.getTasks()).toHaveLength(0);
+});
+
+export default tap.start();

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartcli',
-  version: '4.0.14',
+  version: '4.1.0',
   description: 'A library that simplifies building reactive command-line applications using observables, with robust support for commands, arguments, options, aliases, and asynchronous operation management.'
 }

ts/index.ts

@@ -1 +1,9 @@
 export { Smartcli } from './smartcli.classes.smartcli.js';
+export { SmartcliTerminal, SmartcliTerminalTask } from './smartcli.classes.terminal.js';
+export type {
+  ISmartcliTerminalAttachErrorOptions,
+  ISmartcliTerminalOptions,
+  ISmartcliTerminalTaskOptions,
+  ISmartcliWritable,
+  TSmartcliTerminalTaskStatus,
+} from './smartcli.classes.terminal.js';

ts/smartcli.classes.smartcli.ts

@@ -1,4 +1,5 @@
 import * as plugins from './smartcli.plugins.js';
+import { getUserArgs } from './smartcli.helpers.js';
 
 // interfaces
 export interface ICommandObservableObject {
@@ -17,7 +18,7 @@ export class Smartcli {
    */
   public parseCompleted = plugins.smartpromise.defer<any>();
 
-  public version: string;
+  public version?: string;
 
   /**
    * map of all Trigger/Observable objects to keep track
@@ -64,6 +65,9 @@ export class Smartcli {
    */
   public triggerCommand(commandNameArg: string, argvObject: any) {
     const triggerSubject = this.getCommandSubject(commandNameArg);
+    if (!triggerSubject) {
+      throw new Error(`No smartcli command registered for ${commandNameArg}`);
+    }
     triggerSubject.next(argvObject);
     return triggerSubject;
   }
@@ -91,7 +95,8 @@ export class Smartcli {
    * getOption
    */
   public getOption(optionNameArg: string) {
-    const parsedYargs = plugins.yargsParser(process.argv);
+    const userArgs = getUserArgs();
+    const parsedYargs = plugins.yargsParser(userArgs);
     return parsedYargs[optionNameArg];
   }
 
@@ -121,34 +126,12 @@ export class Smartcli {
 
   /**
    * start the process of evaluating commands
+   * @param testArgv - Optional argv override for testing (bypasses automatic runtime detection)
    */
-  public startParse(): void {
-    const parsedYArgs = plugins.yargsParser([...process.argv]);
-
-    // lets handle commands
-    // Filter out runtime executable and script path from arguments
-    // Node.js: ["/path/to/node", "/path/to/script.js", ...args]
-    // Deno: ["deno", "/path/to/script.ts", ...args]
-    // Bun: ["/path/to/bun", "/path/to/script.ts", ...args]
-    let counter = 0;
-    let foundCommand = false;
-    const runtimeNames = ['node', 'deno', 'bun', 'tsx', 'ts-node'];
-    parsedYArgs._ = parsedYArgs._.filter((commandPartArg) => {
-      counter++;
-      if (typeof commandPartArg === 'number') {
-        return true;
-      }
-      if (counter <= 2 && !foundCommand) {
-        const isPath = commandPartArg.startsWith('/');
-        const isRuntimeExecutable = runtimeNames.some(name =>
-          commandPartArg === name || commandPartArg.endsWith(`/${name}`)
-        );
-        foundCommand = !isPath && !isRuntimeExecutable;
-        return foundCommand;
-      } else {
-        return true;
-      }
-    });
+  public startParse(testArgv?: string[]): void {
+    // Get user arguments, properly handling Node.js, Deno (run/compiled), and Bun
+    const userArgs = testArgv ? getUserArgs(testArgv) : getUserArgs();
+    const parsedYArgs = plugins.yargsParser(userArgs);
     const wantedCommand = parsedYArgs._[0];
 
     // lets handle some standards
@@ -156,7 +139,6 @@ export class Smartcli {
       console.log(this.version || 'unknown version');
       return;
     }
-    console.log(`Wanted command: ${wantedCommand}`);
     for (const command of this.commandObservableMap.getArray()) {
       if (!wantedCommand) {
         const standardCommand = this.commandObservableMap.findSync((commandArg) => {

ts/smartcli.classes.terminal.ts

@@ -0,0 +1,384 @@
+export type TSmartcliTerminalTaskStatus = 'running' | 'completed' | 'failed';
+
+export interface ISmartcliWritable {
+  isTTY?: boolean;
+  columns?: number;
+  write(chunk: string): void | boolean;
+}
+
+export interface ISmartcliTerminalOptions {
+  stream?: ISmartcliWritable;
+  interactive?: boolean;
+  colors?: boolean;
+}
+
+export interface ISmartcliTerminalTaskOptions {
+  job: string;
+  rows?: number;
+  logLimit?: number;
+}
+
+export interface ISmartcliTerminalAttachErrorOptions {
+  keepOpen?: boolean;
+}
+
+const ansiCodes = {
+  reset: '\u001B[0m',
+  red: '\u001B[31m',
+  green: '\u001B[32m',
+  cyan: '\u001B[36m',
+  gray: '\u001B[90m',
+};
+
+/**
+ * A live terminal renderer for multiple fixed-row tasks.
+ * It automatically falls back to append-only logs in non-interactive environments.
+ */
+export class SmartcliTerminal {
+  private stream: ISmartcliWritable;
+  private interactive: boolean;
+  private colors: boolean;
+  private tasks: SmartcliTerminalTask[] = [];
+  private renderedLineCount = 0;
+
+  constructor(optionsArg: ISmartcliTerminalOptions = {}) {
+    this.stream = optionsArg.stream || getDefaultStream();
+    this.interactive = getInteractiveState(this.stream, optionsArg.interactive);
+    this.colors = optionsArg.colors ?? (this.interactive && !hasEnvFlag('NO_COLOR'));
+  }
+
+  public createTask(optionsArg: ISmartcliTerminalTaskOptions): SmartcliTerminalTask {
+    const task = new SmartcliTerminalTask(this, optionsArg);
+    this.tasks.push(task);
+
+    if (this.interactive) {
+      this.render();
+    } else {
+      this.writePermanentLine(`[start] ${task.job}`);
+    }
+
+    return task;
+  }
+
+  public createProcess(optionsArg: ISmartcliTerminalTaskOptions): SmartcliTerminalTask {
+    return this.createTask(optionsArg);
+  }
+
+  public isInteractive(): boolean {
+    return this.interactive;
+  }
+
+  public getTasks(): SmartcliTerminalTask[] {
+    return [...this.tasks];
+  }
+
+  /** @internal */
+  public updateTask(taskArg: SmartcliTerminalTask, messageArg?: string): void {
+    if (!this.tasks.includes(taskArg)) {
+      return;
+    }
+
+    if (this.interactive) {
+      this.render();
+    } else if (messageArg) {
+      this.writePermanentLine(`[${taskArg.job}] ${messageArg}`);
+    }
+  }
+
+  /** @internal */
+  public completeTask(taskArg: SmartcliTerminalTask, messageArg?: string): void {
+    const message = messageArg || taskArg.getLastLogLine();
+    const summary = `[ok] ${taskArg.job}${message ? ` - ${message}` : ''}`;
+    this.finalizeTask(taskArg, [summary]);
+  }
+
+  /** @internal */
+  public failTask(taskArg: SmartcliTerminalTask, errorLinesArg: string[]): void {
+    const summary = `[err] ${taskArg.job}${errorLinesArg[0] ? ` - ${errorLinesArg[0]}` : ''}`;
+    const detailLines = errorLinesArg.slice(1).map((lineArg) => `  ${lineArg}`);
+    this.finalizeTask(taskArg, [summary, ...detailLines]);
+  }
+
+  public clear(): void {
+    if (this.interactive) {
+      this.clearRenderedBlock();
+    }
+    this.tasks = [];
+  }
+
+  private finalizeTask(taskArg: SmartcliTerminalTask, linesArg: string[]): void {
+    this.tasks = this.tasks.filter((task) => task !== taskArg);
+
+    if (this.interactive) {
+      this.clearRenderedBlock();
+      this.writePermanentLines(linesArg);
+      this.render();
+    } else {
+      this.writePermanentLines(linesArg);
+    }
+  }
+
+  private render(): void {
+    if (!this.interactive) {
+      return;
+    }
+
+    const width = this.getLineWidth();
+    const lines = this.tasks.flatMap((taskArg) => {
+      return taskArg.renderPlainRows(width).map((lineArg, indexArg) => {
+        const truncatedLine = truncateLine(lineArg, width);
+        return indexArg === 0 ? this.colorizeStatusLabel(truncatedLine) : truncatedLine;
+      });
+    });
+
+    if (this.renderedLineCount > 0) {
+      this.stream.write(`\u001B[${this.renderedLineCount}F`);
+    }
+
+    const lineCount = Math.max(this.renderedLineCount, lines.length);
+    for (let index = 0; index < lineCount; index++) {
+      this.stream.write('\u001B[2K\r');
+      if (index < lines.length) {
+        this.stream.write(lines[index]);
+      }
+      this.stream.write('\n');
+    }
+
+    this.renderedLineCount = lines.length;
+  }
+
+  private clearRenderedBlock(): void {
+    if (this.renderedLineCount === 0) {
+      return;
+    }
+
+    this.stream.write(`\u001B[${this.renderedLineCount}F`);
+    this.stream.write(`\u001B[${this.renderedLineCount}M`);
+    this.renderedLineCount = 0;
+  }
+
+  private writePermanentLines(linesArg: string[]): void {
+    for (const line of linesArg) {
+      this.writePermanentLine(line);
+    }
+  }
+
+  private writePermanentLine(lineArg: string): void {
+    const line = this.colors ? this.colorizeStatusLabel(lineArg) : lineArg;
+    this.stream.write(`${line}\n`);
+  }
+
+  private colorizeStatusLabel(lineArg: string): string {
+    if (!this.colors) {
+      return lineArg;
+    }
+
+    if (lineArg.startsWith('[ok]')) {
+      return `${ansiCodes.green}[ok]${ansiCodes.reset}${lineArg.slice(4)}`;
+    }
+    if (lineArg.startsWith('[err]')) {
+      return `${ansiCodes.red}[err]${ansiCodes.reset}${lineArg.slice(5)}`;
+    }
+    if (lineArg.startsWith('[run]')) {
+      return `${ansiCodes.cyan}[run]${ansiCodes.reset}${lineArg.slice(5)}`;
+    }
+    if (lineArg.startsWith('[start]')) {
+      return `${ansiCodes.gray}[start]${ansiCodes.reset}${lineArg.slice(7)}`;
+    }
+    return lineArg;
+  }
+
+  private getLineWidth(): number {
+    return Math.max(20, (this.stream.columns || 80) - 1);
+  }
+}
+
+export class SmartcliTerminalTask {
+  public readonly job: string;
+  public readonly rows: number;
+  public status: TSmartcliTerminalTaskStatus = 'running';
+  private terminal: SmartcliTerminal;
+  private logLimit: number;
+  private logLines: string[] = [];
+  private errorLines: string[] = [];
+
+  constructor(terminalArg: SmartcliTerminal, optionsArg: ISmartcliTerminalTaskOptions) {
+    this.terminal = terminalArg;
+    this.job = optionsArg.job;
+    this.rows = Math.max(1, Math.floor(optionsArg.rows || 3));
+    this.logLimit = Math.max(this.rows, Math.floor(optionsArg.logLimit || 100));
+  }
+
+  public log(messageArg: string): this {
+    if (this.status !== 'running') {
+      return this;
+    }
+
+    const newLines = normalizeLines(messageArg);
+    this.logLines.push(...newLines);
+    if (this.logLines.length > this.logLimit) {
+      this.logLines.splice(0, this.logLines.length - this.logLimit);
+    }
+
+    this.terminal.updateTask(this, newLines.join('\n'));
+    return this;
+  }
+
+  public update(messageArg: string): this {
+    return this.log(messageArg);
+  }
+
+  public complete(messageArg?: string): this {
+    if (this.status !== 'running') {
+      return this;
+    }
+
+    this.status = 'completed';
+    this.terminal.completeTask(this, messageArg);
+    return this;
+  }
+
+  public attachError(
+    errorArg: unknown,
+    optionsArg: ISmartcliTerminalAttachErrorOptions = {}
+  ): this {
+    if (this.status !== 'running') {
+      return this;
+    }
+
+    this.status = 'failed';
+    this.errorLines = formatError(errorArg);
+
+    if (optionsArg.keepOpen) {
+      this.terminal.updateTask(this, this.errorLines.join('\n'));
+    } else {
+      this.terminal.failTask(this, this.errorLines);
+    }
+
+    return this;
+  }
+
+  public fail(errorArg: unknown): this {
+    return this.attachError(errorArg);
+  }
+
+  public getLastLogLine(): string | undefined {
+    return this.logLines[this.logLines.length - 1];
+  }
+
+  public getLogLines(): string[] {
+    return [...this.logLines];
+  }
+
+  public getErrorLines(): string[] {
+    return [...this.errorLines];
+  }
+
+  /** @internal */
+  public renderPlainRows(widthArg: number): string[] {
+    const statusLabel = this.status === 'failed' ? '[err]' : '[run]';
+    const lines: string[] = [];
+    const detailLines = this.errorLines.length > 0 ? this.errorLines : this.logLines;
+
+    if (this.rows === 1) {
+      const lastDetail = detailLines[detailLines.length - 1];
+      lines.push(`${statusLabel} ${this.job}${lastDetail ? ` - ${lastDetail}` : ''}`);
+      return lines;
+    }
+
+    lines.push(`${statusLabel} ${this.job}`);
+    const visibleDetailLineCount = this.rows - 1;
+    const visibleDetailLines = detailLines.slice(-visibleDetailLineCount);
+    for (const line of visibleDetailLines) {
+      lines.push(`  ${line}`);
+    }
+
+    while (lines.length < this.rows) {
+      lines.push('');
+    }
+
+    return lines.map((lineArg) => truncateLine(lineArg, widthArg));
+  }
+}
+
+function getDefaultStream(): ISmartcliWritable {
+  const globalObject: any = globalThis as any;
+  if (globalObject.process?.stdout?.write) {
+    return globalObject.process.stdout;
+  }
+
+  return {
+    isTTY: false,
+    write: (chunkArg: string) => {
+      if (typeof console !== 'undefined') {
+        console.log(chunkArg.replace(/\n$/, ''));
+      }
+    },
+  };
+}
+
+function getInteractiveState(streamArg: ISmartcliWritable, overrideArg?: boolean): boolean {
+  if (typeof overrideArg === 'boolean') {
+    return overrideArg;
+  }
+
+  if (!streamArg.isTTY) {
+    return false;
+  }
+
+  return !(
+    hasEnvFlag('CI') ||
+    hasEnvFlag('GITHUB_ACTIONS') ||
+    hasEnvFlag('JENKINS_URL') ||
+    hasEnvFlag('GITLAB_CI') ||
+    hasEnvFlag('TRAVIS') ||
+    hasEnvFlag('CIRCLECI') ||
+    getEnvValue('TERM') === 'dumb'
+  );
+}
+
+function hasEnvFlag(nameArg: string): boolean {
+  const value = getEnvValue(nameArg);
+  return Boolean(value && value !== '0' && value.toLowerCase() !== 'false');
+}
+
+function getEnvValue(nameArg: string): string | undefined {
+  const globalObject: any = globalThis as any;
+  return globalObject.process?.env?.[nameArg];
+}
+
+function normalizeLines(messageArg: string): string[] {
+  return String(messageArg)
+    .split(/\r?\n/)
+    .map((lineArg) => lineArg.trimEnd())
+    .filter((lineArg) => lineArg.length > 0);
+}
+
+function formatError(errorArg: unknown): string[] {
+  if (errorArg instanceof Error) {
+    return normalizeLines(errorArg.stack || errorArg.message || errorArg.name);
+  }
+
+  if (typeof errorArg === 'string') {
+    return normalizeLines(errorArg);
+  }
+
+  try {
+    const jsonString = JSON.stringify(errorArg);
+    return normalizeLines(jsonString === undefined ? String(errorArg) : jsonString);
+  } catch {
+    return [String(errorArg)];
+  }
+}
+
+function truncateLine(lineArg: string, widthArg: number): string {
+  if (lineArg.length <= widthArg) {
+    return lineArg;
+  }
+
+  if (widthArg <= 3) {
+    return lineArg.slice(0, widthArg);
+  }
+
+  return `${lineArg.slice(0, widthArg - 3)}...`;
+}

ts/smartcli.helpers.ts

@@ -0,0 +1,76 @@
+/**
+ * Return only the user arguments (excluding runtime executable and script path),
+ * across Node.js, Deno (run/compiled), and Bun.
+ *
+ * - Deno: uses Deno.args directly (already user-only in both run and compile).
+ * - Node/Bun: uses process.execPath's basename to decide if there is a script arg.
+ *   If execPath basename is a known launcher (node/nodejs/bun/deno), skip 2; else skip 1.
+ */
+export function getUserArgs(argv?: string[]): string[] {
+  // If argv is explicitly provided, use it instead of Deno.args
+  // This handles test scenarios where process.argv is manually modified
+  const useProvidedArgv = argv !== undefined;
+
+  // Prefer Deno.args when available and no custom argv provided;
+  // it's the most reliable for Deno run and compiled.
+  // Deno.args is ALWAYS correct in Deno environments - it handles the internal bundle path automatically.
+  // deno-lint-ignore no-explicit-any
+  const g: any = typeof globalThis !== 'undefined' ? globalThis : {};
+
+  if (!useProvidedArgv && g.Deno && g.Deno.args && Array.isArray(g.Deno.args)) {
+    return g.Deno.args.slice();
+  }
+
+  const a = argv ?? (typeof process !== 'undefined' && Array.isArray(process.argv) ? process.argv : []);
+
+  if (!Array.isArray(a) || a.length === 0) return [];
+
+  // Determine execPath in Node/Bun (or compat shims)
+  let execPath = '';
+  if (typeof process !== 'undefined' && typeof process.execPath === 'string') {
+    execPath = process.execPath;
+  } else if (g.Deno && typeof g.Deno.execPath === 'function') {
+    // Fallback for unusual shims: try Deno.execPath() if present.
+    try {
+      execPath = g.Deno.execPath();
+    } catch {
+      /* ignore */
+    }
+  }
+
+  const base = basename(execPath).toLowerCase();
+  const knownLaunchers = new Set([
+    'node',
+    'node.exe',
+    'nodejs',
+    'nodejs.exe',
+    'bun',
+    'bun.exe',
+    'deno',
+    'deno.exe',
+    'tsx',
+    'tsx.exe',
+    'ts-node',
+    'ts-node.exe',
+  ]);
+
+  // Always skip the executable (argv[0]).
+  let offset = Math.min(1, a.length);
+
+  // If the executable is a known runtime launcher, there's almost always a script path in argv[1].
+  // This handles Node, Bun, and "deno run" (but NOT "deno compile" which won't match 'deno').
+  if (knownLaunchers.has(base)) {
+    offset = Math.min(2, a.length);
+  }
+
+  // Note: we intentionally avoid path/URL heuristics on argv[1] so we don't
+  // accidentally drop the first user arg when it's a path-like value in compiled mode.
+  // When offset >= a.length, this correctly returns an empty array (no user args).
+  return a.slice(offset);
+}
+
+function basename(p: string): string {
+  if (!p) return '';
+  const parts = p.split(/[/\\]/);
+  return parts[parts.length - 1] || '';
+}

tsconfig.json

@@ -5,10 +5,10 @@
     "target": "ES2022",
     "module": "NodeNext",
     "moduleResolution": "NodeNext",
+    "noImplicitAny": true,
     "esModuleInterop": true,
-    "verbatimModuleSyntax": true
+    "verbatimModuleSyntax": true,
+    "types": ["node"]
   },
-  "exclude": [
-    "dist_*/**/*.d.ts"
-  ]
+  "exclude": ["dist_*/**/*.d.ts"]
 }