smart-spinner 1.0.1 → 1.1.0

package/.ocmux.json

@@ -0,0 +1 @@
+{"url":"http://127.0.0.1:33469","logfile":"/tmp/opencode-serve-3370b8294dc3.log","window_index":4}

package/AGENTS.md

@@ -0,0 +1,19 @@
+# smart-spinner — agent guide
+
+Single-file npm package (`index.js`). No build, no tests, no CI.
+
+## Commands
+
+- **Run examples:** `node examples/simple-example.js` (from project root; uses `require("../")`)
+- **Test:** none — `npm test` is a no-op stub
+
+## Key architecture
+
+- `spinner.create(msg, opts)` → returns `ctrlAPI(stopOrMsg, newMsg?)` — `opts` is an options object (`{ spinners, timestamp }`). For backward compat, a string/array is accepted as shorthand for `{ spinners: value }`. The returned API is overloaded: pass a `boolean` to stop, a `string`/`function` to update the message, or both. Also has `ctrlAPI.update(newMsg)` for non-TTY phase transitions.
+- `opts.timestamp` (`'utc'`, `'local'`, or IANA timezone) prepends ISO-8601 timestamps to non-TTY log lines.
+- Non-TTY detection (`tty.isatty`) silences animation; only the initial message + updates are `console.log`-ed once.
+- `has-unicode` / `chalk` graceful fallback for non-Unicode / no-color terminals.
+
+## Dependencies (old majors)
+
+`chalk@^2`, `cli-spinners@^1`, `log-update@^2`, `has-unicode@^2` — be aware if bumping.

package/README.md

@@ -84,7 +84,7 @@ const spinner = require("smart-spinner");
 
 
 ```javascript
-var progress = spinner.create(<message> [, <spinner_list>]);
+var progress = spinner.create(<message> [, <opts>]);
 ```
 
 **Where:**
@@ -94,25 +94,38 @@ var progress = spinner.create(<message> [, <spinner_list>]);
     is actually connected to terminal or not. So complex calculations can be
     avoided if needed (also callback will be called single time in this case).
     
-  * `<spinner_list>`: Array of spinner names (See [list()](#list) or
-    [demo()](#demo) to know which ones are available) or string "all" to use
-    all.
-    - Specified spinners will be rotated regularly.
-    - If "all" keyword is specified instead, all available ones will be used.
-    - If "demo" keyword is specified instead, it will operate just like if
-      [demo()](#demo) were used instead.
-    - If string (distinct of "all" and "demo" is used) it wil be threated as
-      single spinner list.
+  * `<opts>`: Optional options object with the following properties:
 
+    - `spinners` (string|Array): Spinner name or list of spinner names (See
+      [list()](#list) or [demo()](#demo) to know which ones are available).
+      Use `"all"` to rotate through all available spinners, or `"demo"` to
+      show spinner names as they rotate. Default: `['dots']`.
 
-**Return value:** Callback to control spinner:
+    - `timestamp` (boolean|string): Prepend ISO-8601 timestamp to non-TTY
+      log lines. Use `'utc'` (or `true`) for UTC, `'local'` for local
+      timezone, or any IANA timezone string (e.g. `'America/New_York'`).
+      Default: none.
 
-__Syntax:__
+> **Note:** For backward compatibility, the second parameter also accepts a
+> string or array directly as a shorthand for `{ spinners: <value> }`.
+> The old 3-argument form `create(msg, spinners, opts)` is deprecated.
+
+
+**Return value:** Control API with the following methods:
+
+__Function call syntax:__
 
   * `progress (String <newMsg>)`: Set message to provided string or callback.
   * `progress (Boolean <stop>)`: Stop spinning with success (stop = true) or failed (stop = false).
   * `progress (Boolean <stop>, String <newMsg>)` Stop spinning but also updates message.
 
+__Method syntax:__
+
+  * `progress.update(String|Function <newMsg>)`: Replace the message callback
+    and immediately emit a new line in non-TTY mode (does nothing on
+    interactive terminals — the animation loop picks up the new callback
+    automatically).
+
 
 
 ### Other functions

package/examples/timestamp-demo.js

@@ -0,0 +1,31 @@
+"use strict";
+// Run me with 'node path/to/examples/simple-example.js'.
+
+const spinner = require("../");
+
+var progress = spinner.create("Here a Spinner with timestamp", {timestamp: "local"});
+
+// Also try using demo() instead:
+// var progress = spinner.demo();
+
+setTimeout(()=>{
+    progress("If you don't see it, try to pipe the output to a file or a command like `cat`.");
+}, 2000);
+
+
+setTimeout(()=>{
+    progress(function(){
+        var someStatus = (new Date()).toLocaleString();
+        return "You already know that current time is: " + someStatus;
+    });
+}, 4000);
+
+
+setTimeout(()=>{
+    progress("But if you read a logged file later, you won't.");
+}, 6000);
+
+setTimeout(()=>Math.round(Math.random())
+    ?  progress(true, "Job done!!")
+    :  progress(false, "Error!!")
+, 8000);

package/index.js

@@ -39,7 +39,14 @@ if (
 // ===================//}}}
 
 
-function smartSpinner(cbk, spinners = ['dots']) {//{{{
+function smartSpinner(cbk, opts = {}) {//{{{
+
+    // Backward compat: if opts is a string or array, treat as spinner list:
+    if (typeof opts === 'string' || Array.isArray(opts)) {
+        opts = { spinners: opts };
+    };
+
+    var spinners = opts.spinners !== undefined ? opts.spinners : ['dots'];
 
     var messageCbk;
 
@@ -49,6 +56,45 @@ function smartSpinner(cbk, spinners = ['dots']) {//{{{
     let next;
     let is_tty = tty.isatty(process.stdout.fd);
 
+    var tsEnabled = !!(opts && opts.timestamp);
+    var tsOpt = opts && opts.timestamp;
+    if (tsEnabled) {
+        if (tsOpt === true) tsOpt = 'utc';
+        if (typeof tsOpt !== 'string') tsOpt = 'utc';
+    };
+    function fmtTS() {
+        if (!tsEnabled) return '';
+        var now = new Date();
+        var s;
+        if (tsOpt === 'utc') {
+            s = now.toISOString().replace(/\.\d+Z$/, 'Z');
+        } else {
+            var dtfOpt = {
+                year: 'numeric', month: '2-digit', day: '2-digit',
+                hour: '2-digit', minute: '2-digit', second: '2-digit',
+                hour12: false, timeZoneName: 'shortOffset'
+            };
+            if (tsOpt !== 'local') dtfOpt.timeZone = tsOpt;
+            var map = {};
+            Intl.DateTimeFormat('en-CA', dtfOpt).formatToParts(now).forEach(function(p) { map[p.type] = p.value; });
+            var tz = map.timeZoneName || 'Z';
+            if (tz === 'UTC') tz = 'Z';
+            else if (tz.slice(0, 3) === 'GMT') {
+                var off = tz.slice(3);
+                if (!off) { tz = 'Z'; }
+                else {
+                    var sign = off.charAt(0);
+                    var rest = off.slice(1);
+                    var parts = rest.split(':');
+                    var hh = parts[0].length < 2 ? '0' + parts[0] : parts[0];
+                    var mm = parts[1] ? (parts[1].length < 2 ? '0' + parts[1] : parts[1]) : '00';
+                    tz = sign + hh + ':' + mm;
+                };
+            };
+            s = map.year + '-' + map.month + '-' + map.day + 'T' + map.hour + ':' + map.minute + ':' + map.second + tz;
+        };
+        return '[' + s + '] ';
+    };
 
     function showNextFrame () {//{{{
         const frames = cliSpinners[spinners[spinner]].frames;
@@ -77,7 +123,7 @@ function smartSpinner(cbk, spinners = ['dots']) {//{{{
                 if (stop !== undefined) {
                     stop || process.stdout.write("\n");
                 } else {
-                    console.log(symbols.arrow + ' ' + messageCbk(false));
+                    console.log(fmtTS() + symbols.arrow + ' ' + messageCbk(false));
                 };
             };
         };
@@ -88,15 +134,25 @@ function smartSpinner(cbk, spinners = ['dots']) {//{{{
             stopped = true;
 
             let s = symbols[stop ? "ok" : "error"];
-            logUpdate(s + ' ' + messageCbk(true));
-
-            if (is_tty) process.stdout.write("\n");
+            if (is_tty) {
+                logUpdate(s + ' ' + messageCbk(true));
+                process.stdout.write("\n");
+            } else {
+                console.log(fmtTS() + s + ' ' + messageCbk(true));
+            };
         }
 
         return true; // Success.
 
     };//}}}
 
+    ctrlAPI.update = function (newCbk) {
+        messageCbk = ("function" == typeof newCbk) ? newCbk : ()=>newCbk;
+        if (!is_tty) {
+            console.log(fmtTS() + symbols.arrow + ' ' + messageCbk(false));
+        };
+    };
+
     ctrlAPI(cbk);
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smart-spinner",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Simple cli-spinners wrapper.",
   "main": "index.js",
   "scripts": {

package/smart-spinner-tasks.md

@@ -0,0 +1,191 @@
+# smart-spinner: pending modifications
+
+## Task 1: Remove `\r` control characters from non-TTY output on stop
+
+**Location:** `index.js`, stop block (lines ~86–94)
+
+**Problem:** When output is not a TTY (e.g. `cmt_import | tee log`), the stop
+path calls `logUpdate()` unconditionally. `logUpdate` writes `\r` to overwrite
+the current line, which is fine on a terminal but leaves literal `\r` garbage
+in log files when viewed in editors like vim (though `cat`/`less` handle them).
+
+**Fix:** In the stop block (`if (stop !== undefined) { ... }`), branch on
+`is_tty`:
+
+```js
+if (is_tty) {
+    logUpdate(s + ' ' + messageCbk(true));
+    process.stdout.write('\n');
+} else {
+    console.log(s + ' ' + messageCbk(true));
+}
+```
+
+This mirrors the existing non-TTY branch already used in the update path
+(around line 80): `console.log` writes plain text with a final newline, no
+`\r`.
+
+## Task 2: Expose an `update()` method so the client can trigger a new non-TTY log line
+
+**Location:** `index.js`, the control API returned by `spinner.create()`
+
+**Problem:** Smart-spinner's `create(fn)` takes a single callback. When the
+client's internal phase changes (e.g. from md5-computation to XML-loading),
+the client needs the spinner to emit a fresh progress line in non-TTY mode.
+Currently, the non-TTY `console.log` only fires when the callback is first
+set (line ~80), so phase transitions stay silent — the log never shows the
+new phase message.
+
+The client workaround is to stop and re-create the spinner, which is
+cumbersome and loses the visual continuity.
+
+**Fix:** Add an `update()` method to the control API that:
+1. Replaces the internal callback reference.
+2. If `!is_tty`, immediately calls `console.log(messageCbk(false))` to emit
+   the new message.
+
+Signature: `ctrlAPI.update(newCallback)` — `newCallback` replaces the
+original callback and a non-TTY line is written synchronously.
+
+If `is_tty` (interactive terminal), `update()` does nothing — the animation
+loop already picks up the new callback on the next tick, so no special
+handling is needed.
+
+```js
+ctrlAPI.update = function (newCbk) {
+    messageCbk = newCbk;
+    if (!is_tty) {
+        console.log(messageCbk(false));
+    }
+};
+```
+
+**Client usage:**
+
+```js
+var progress = spinner.create(function (interactive) {
+    if (phase === 'md5') return interactive ? 'Hashing...' : 'Hashing...';
+    return interactive ? 'Loading...' : 'Loading...';
+});
+
+// When phase changes:
+phase = 'loading';
+progress.update(function (interactive) {
+    return 'Loading...';
+});
+```
+
+This is purely additive — no existing behaviour changes. The client is free
+to ignore `update()` and just stop/recreate as before.
+
+## Task 3: Add timestamp prefix to non-TTY output
+
+**Location:** `index.js`, the `spinner.create()` function signature and all
+`console.log` call sites in the non-TTY branches.
+
+**Problem:** When reading log files from a non-interactive run, there's no way
+to tell when each progress line was emitted. The client currently works around
+this by embedding timestamps in the callback message itself, but this is
+verbose, inconsistent, and forces every client to reimplement the same logic.
+
+**Goal:** Add an optional `timestamp` parameter to `spinner.create` that, when
+enabled, prepends an ISO-8601 timestamp to every non-TTY output line.
+
+**API change:**
+
+```js
+// Current — no timestamps (backward compatible):
+spinner.create(cbk)
+spinner.create(cbk, {})
+
+// New — with timestamps:
+spinner.create(cbk, { timestamp: 'utc' })    // [2026-06-05T13:03:40Z]
+spinner.create(cbk, { timestamp: 'local' })  // [2026-06-05T15:03:40+02:00]
+```
+
+- When `opts.timestamp` is `true`, behave as `'utc'`.
+- When falsy or absent, no timestamp is prepended.
+- Any other string value is passed through to the `Intl.DateTimeFormat`
+  `timeZone` option (e.g. `'America/New_York'`), so it Just Works for any
+  IANA timezone.
+
+**Implementation:**
+
+1. Change the `create` signature from `create(messageCbk)` to
+   `create(messageCbk, opts)` where `opts` defaults to `{}`.
+
+2. Compute a `ts` helper function (or inline it) at the top of the function
+   body:
+
+   ```js
+   var tsEnabled = !!(opts && opts.timestamp);
+   var tsOpt = opts && opts.timestamp;
+   if (tsEnabled) {
+       // true → 'utc', already a string → use as-is, else 'utc'
+       if (tsOpt === true) tsOpt = 'utc';
+       if (typeof tsOpt !== 'string') tsOpt = 'utc';
+   }
+   function fmtTS() {
+       if (!tsEnabled) return '';
+       var now = new Date();
+       var s;
+       if (tsOpt === 'utc') {
+           s = now.toISOString(); // always Z
+       } else {
+           // local or arbitrary IANA timezone
+           var opt = { year: 'numeric', month: '2-digit', day: '2-digit',
+                       hour: '2-digit', minute: '2-digit', second: '2-digit',
+                       timeZoneName: 'shortOffset', timeZone: tsOpt };
+           var parts = Intl.DateTimeFormat('en-CA', opt).formatToParts(now);
+           // format as YYYY-MM-DDTHH:mm:ss±HH:mm (ISO 8601)
+           // … assembly logic
+       }
+       return '[' + s + '] ';
+   }
+   ```
+
+3. Prepend `fmtTS()` to every non-TTY `console.log` call. There are three
+   such sites:
+   - The initial log line when the callback is first registered (around line 80):
+     `console.log(fmtTS() + '→ ' + messageCbk(false));`
+   - The `update()` path added in Task 2:
+     `console.log(fmtTS() + messageCbk(false));`
+   - The stop path (Task 1):
+     `console.log(fmtTS() + s + ' ' + messageCbk(true));`
+
+   (The `→` symbol is only used in the initial/update log lines, not in the
+   stop line, since the stop already has the ✓/✗ symbol.)
+
+4. The interactive (TTY) path is **not** modified — timestamps would clutter
+   the animated spinner line.
+
+**Client migration:**
+
+Once this is published, the client removes its own timestamp formatting and
+passes the option instead:
+
+```js
+// Before (cmt_import.js):
+var progress = spinner.create(function (interactive) {
+    if (phase === 'md5') return interactive
+        ? "Calculating file hash (md5)..."
+        : "[" + new Date().toISOString() + "] Calculating file hash (md5)...";
+    // ...
+});
+
+// After:
+var progress = spinner.create(function (interactive) {
+    if (phase === 'md5') return "Calculating file hash (md5)...";
+    // ...
+}, { timestamp: 'utc' });
+```
+
+The `update()` method receives the same `opts` automatically (no need to
+pass it again on every call).
+
+**Edge cases:**
+- `Intl.DateTimeFormat` throws on invalid timezone strings. Let it propagate
+  — the developer will fix their config.
+- `en-CA` locale gives `YYYY-MM-DD` format naturally. If the browser/runtime
+  doesn't support `en-CA`, fall back to manual `padStart` construction.
+  (Node.js supports it since v13, so this is not a concern in practice.)