osc-progress 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+All notable changes to this project are documented in this file.
+
+## 0.1.0 - 2025-12-19
+### Added
+- OSC 9;4 progress emitter (`startOscProgress`) with determinate (`0% → 99%`) and indeterminate modes.
+- Terminal support detection (`supportsOscProgress`) with safe defaults (TTY-only) and heuristics for Ghostty / WezTerm / Windows Terminal.
+- Environment overrides (`force`/`disabled` and `forceEnvVar`/`disableEnvVar`).
+- OSC 9;4 stripping/sanitizing helpers (`stripOscProgress`, `sanitizeOscProgress`) for log storage.
+- Sequence finder (`findOscProgressSequences`) supporting ST (`ESC \\`), BEL, and C1 ST terminators.
+- Label sanitization (`sanitizeLabel`) to prevent control/terminator injection.
+- Modern TypeScript ESM package with bundled types, Node 20+.
+- Test suite with full coverage for core behavior.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Peter Steinberger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,77 @@
+# ⏳ osc-progress — Tiny lib for OSC 9;4 terminal progress.
+
+Tiny TypeScript helper for **OSC 9;4** terminal progress sequences (used by terminals like Ghostty / WezTerm / Windows Terminal).
+
+## Install
+
+```bash
+pnpm add osc-progress
+```
+
+## Usage
+
+```ts
+import process from 'node:process'
+import { startOscProgress } from 'osc-progress'
+
+const stop = startOscProgress({
+  label: 'Fetching',
+  write: (chunk) => process.stderr.write(chunk),
+  env: process.env,
+  isTty: process.stderr.isTTY,
+})
+
+// ...do work...
+
+stop()
+```
+
+Indeterminate (spinner-like) mode:
+
+```ts
+import { startOscProgress } from 'osc-progress'
+
+const stop = startOscProgress({ label: 'Waiting', indeterminate: true })
+// ...
+stop()
+```
+
+Strip OSC progress from stored logs:
+
+```ts
+import { sanitizeOscProgress } from 'osc-progress'
+
+const clean = sanitizeOscProgress(text, /*keepOsc*/ process.stdout.isTTY)
+```
+
+## API
+
+### `supportsOscProgress(env?, isTty?, options?)`
+
+Returns `true` when emitting OSC 9;4 progress makes sense.
+
+Heuristics:
+- requires a TTY
+- enables for `TERM_PROGRAM=ghostty*`, `TERM_PROGRAM=wezterm*`, or `WT_SESSION` (Windows Terminal)
+
+Optional overrides:
+- `options.disabled` / `options.force`
+- `options.disableEnvVar` / `options.forceEnvVar` (expects `= "1"`)
+
+### `startOscProgress(options?)`
+
+Starts a best-effort progress indicator and returns `stop(): void`.
+
+Notes:
+- `label` is appended as extra payload; **not part of the canonical OSC 9;4 spec** (many terminals ignore it, some show it).
+- default is a timer-driven `0% → 99%` progression (never completes by itself).
+- `terminator` defaults to `st` (`ESC \\`); `bel` is also supported.
+
+### `sanitizeOscProgress(text, keepOsc)`
+
+Removes OSC 9;4 progress sequences (terminated by `BEL`, `ST` (`ESC \\`), or `0x9c`).
+
+## Semantics / portability
+
+OSC 9;4 is widely implemented, but state `4` is ambiguous across terminals (some treat it as `paused`, some as `warning`).
+This library exposes the raw numeric state and does not try to reinterpret it.

package/dist/esm/index.js

@@ -0,0 +1,2 @@
+export { findOscProgressSequences, OSC_PROGRESS_BEL, OSC_PROGRESS_C1_ST, OSC_PROGRESS_PREFIX, OSC_PROGRESS_ST, sanitizeLabel, sanitizeOscProgress, startOscProgress, stripOscProgress, supportsOscProgress, } from './oscProgress.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,EACxB,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,EACnB,eAAe,EAKf,aAAa,EACb,mBAAmB,EACnB,gBAAgB,EAChB,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,kBAAkB,CAAA"}

package/dist/esm/oscProgress.js

@@ -0,0 +1,195 @@
+import process from 'node:process';
+/**
+ * OSC 9;4 progress prefix (`ESC ] 9 ; 4 ;`).
+ *
+ * Typical emitted forms:
+ * - `ESC ] 9;4;<state>;<percent>;<payload> ST`
+ * - `ESC ] 9;4;<state>;;<payload> ST` (indeterminate)
+ */
+export const OSC_PROGRESS_PREFIX = '\u001b]9;4;';
+/** String Terminator (ST): `ESC \\` */
+export const OSC_PROGRESS_ST = '\u001b\\';
+/** Bell (BEL): `0x07` */
+export const OSC_PROGRESS_BEL = '\u0007';
+/** C1 String Terminator (ST): `0x9c` */
+export const OSC_PROGRESS_C1_ST = '\u009c';
+function resolveTerminator(terminator) {
+    return terminator === 'bel' ? OSC_PROGRESS_BEL : OSC_PROGRESS_ST;
+}
+/**
+ * Sanitizes a label/payload so it can't break the surrounding OSC sequence.
+ * Removes escape chars and common OSC terminators; trims whitespace.
+ */
+export function sanitizeLabel(label) {
+    const withoutSt = label.replaceAll(OSC_PROGRESS_ST, '');
+    const withoutEscape = withoutSt.split('\u001b').join('');
+    const withoutTerminators = withoutEscape
+        .replaceAll(OSC_PROGRESS_BEL, '')
+        .replaceAll(OSC_PROGRESS_C1_ST, '');
+    return withoutTerminators.replaceAll(']', '').trim();
+}
+/**
+ * Best-effort check whether OSC 9;4 progress output is likely to work.
+ *
+ * Default heuristics:
+ * - requires `isTty === true`
+ * - enables for Ghostty (`TERM_PROGRAM=ghostty*`), WezTerm (`TERM_PROGRAM=wezterm*`), Windows Terminal (`WT_SESSION`)
+ *
+ * Override knobs:
+ * - `options.force` / `options.disabled`
+ * - `options.forceEnvVar` / `options.disableEnvVar` (expects value `"1"`)
+ */
+export function supportsOscProgress(env = process.env, isTty = process.stdout.isTTY, options = {}) {
+    if (!isTty)
+        return false;
+    if (options.disabled)
+        return false;
+    if (options.force)
+        return true;
+    if (options.disableEnvVar && env[options.disableEnvVar] === '1') {
+        return false;
+    }
+    if (options.forceEnvVar && env[options.forceEnvVar] === '1') {
+        return true;
+    }
+    const termProgram = (env.TERM_PROGRAM ?? '').toLowerCase();
+    if (termProgram.includes('ghostty'))
+        return true;
+    if (termProgram.includes('wezterm'))
+        return true;
+    if (env.WT_SESSION)
+        return true;
+    return false;
+}
+/**
+ * Finds OSC 9;4 progress sequences inside an arbitrary string.
+ *
+ * Supports three terminators:
+ * - ST (`ESC \\`)
+ * - BEL (`0x07`)
+ * - C1 ST (`0x9c`)
+ *
+ * Unterminated sequences are ignored (use `stripOscProgress` if you want to drop them).
+ */
+export function findOscProgressSequences(text) {
+    const sequences = [];
+    const prefixLen = OSC_PROGRESS_PREFIX.length;
+    let searchFrom = 0;
+    while (searchFrom < text.length) {
+        const start = text.indexOf(OSC_PROGRESS_PREFIX, searchFrom);
+        if (start === -1)
+            break;
+        const after = start + prefixLen;
+        const candidates = [];
+        const stStart = text.indexOf(OSC_PROGRESS_ST, after);
+        if (stStart !== -1) {
+            candidates.push({ endExclusive: stStart + OSC_PROGRESS_ST.length, terminator: 'st' });
+        }
+        const belStart = text.indexOf(OSC_PROGRESS_BEL, after);
+        if (belStart !== -1) {
+            candidates.push({ endExclusive: belStart + OSC_PROGRESS_BEL.length, terminator: 'bel' });
+        }
+        const c1Start = text.indexOf(OSC_PROGRESS_C1_ST, after);
+        if (c1Start !== -1) {
+            candidates.push({ endExclusive: c1Start + OSC_PROGRESS_C1_ST.length, terminator: 'c1st' });
+        }
+        if (candidates.length === 0) {
+            searchFrom = after;
+            continue;
+        }
+        candidates.sort((a, b) => a.endExclusive - b.endExclusive);
+        const best = candidates[0];
+        sequences.push({
+            start,
+            end: best.endExclusive,
+            raw: text.slice(start, best.endExclusive),
+            terminator: best.terminator,
+        });
+        searchFrom = best.endExclusive;
+    }
+    return sequences;
+}
+/**
+ * Removes OSC 9;4 progress sequences from `text`.
+ *
+ * Behavior:
+ * - strips sequences terminated by ST/BEL/C1 ST
+ * - if a sequence is unterminated, it is removed until end-of-string
+ */
+export function stripOscProgress(text) {
+    const prefixLen = OSC_PROGRESS_PREFIX.length;
+    let current = text;
+    while (current.includes(OSC_PROGRESS_PREFIX)) {
+        const start = current.indexOf(OSC_PROGRESS_PREFIX);
+        const after = start + prefixLen;
+        const stStart = current.indexOf(OSC_PROGRESS_ST, after);
+        const belStart = current.indexOf(OSC_PROGRESS_BEL, after);
+        const c1Start = current.indexOf(OSC_PROGRESS_C1_ST, after);
+        const ends = [];
+        if (stStart !== -1)
+            ends.push(stStart + OSC_PROGRESS_ST.length);
+        if (belStart !== -1)
+            ends.push(belStart + OSC_PROGRESS_BEL.length);
+        if (c1Start !== -1)
+            ends.push(c1Start + OSC_PROGRESS_C1_ST.length);
+        const cutEnd = ends.length === 0 ? current.length : Math.min(...ends);
+        current = `${current.slice(0, start)}${current.slice(cutEnd)}`;
+    }
+    return current;
+}
+/**
+ * Convenience helper:
+ * - if `keepOsc` is true, returns the input unchanged (useful when writing to a TTY)
+ * - otherwise, strips OSC 9;4 sequences (useful for logs/snapshots)
+ */
+export function sanitizeOscProgress(text, keepOsc) {
+    return keepOsc ? text : stripOscProgress(text);
+}
+/**
+ * Emits a terminal progress indicator using OSC 9;4 and returns `stop()`.
+ *
+ * Notes:
+ * - no-op when `supportsOscProgress(...)` is false
+ * - determinate mode ramps `0% → 99%` on a timer; `stop()` clears progress
+ * - indeterminate mode emits `state=3` and `stop()` clears progress
+ */
+export function startOscProgress(options = {}) {
+    const { label = 'Working…', targetMs = 10 * 60_000, write = (text) => process.stderr.write(text), indeterminate = false, state = 1, terminator, } = options;
+    if (!supportsOscProgress(options.env, options.isTty, options)) {
+        return () => { };
+    }
+    const cleanLabel = sanitizeLabel(label);
+    const end = resolveTerminator(terminator);
+    const send = (st, percent) => {
+        if (percent == null) {
+            write(`${OSC_PROGRESS_PREFIX}${st};;${cleanLabel}${end}`);
+            return;
+        }
+        const clamped = Math.max(0, Math.min(100, Math.round(percent)));
+        write(`${OSC_PROGRESS_PREFIX}${st};${clamped};${cleanLabel}${end}`);
+    };
+    if (indeterminate) {
+        send(3, null);
+        return () => {
+            send(0, 0);
+        };
+    }
+    const target = Math.max(targetMs, 1_000);
+    const startedAt = Date.now();
+    send(state, 0);
+    const timer = setInterval(() => {
+        const elapsed = Date.now() - startedAt;
+        const percent = Math.min(99, (elapsed / target) * 100);
+        send(state, percent);
+    }, 900);
+    timer.unref?.();
+    let stopped = false;
+    return () => {
+        if (stopped)
+            return;
+        stopped = true;
+        clearInterval(timer);
+        send(0, 0);
+    };
+}
+//# sourceMappingURL=oscProgress.js.map

package/dist/esm/oscProgress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oscProgress.js","sourceRoot":"","sources":["../../src/oscProgress.ts"],"names":[],"mappings":"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"}

package/dist/types/index.d.ts

@@ -0,0 +1 @@
+export { findOscProgressSequences, OSC_PROGRESS_BEL, OSC_PROGRESS_C1_ST, OSC_PROGRESS_PREFIX, OSC_PROGRESS_ST, type OscProgressOptions, type OscProgressSequence, type OscProgressSupportOptions, type OscProgressTerminator, sanitizeLabel, sanitizeOscProgress, startOscProgress, stripOscProgress, supportsOscProgress, } from './oscProgress.js';

package/dist/types/oscProgress.d.ts

@@ -0,0 +1,117 @@
+/**
+ * OSC 9;4 progress prefix (`ESC ] 9 ; 4 ;`).
+ *
+ * Typical emitted forms:
+ * - `ESC ] 9;4;<state>;<percent>;<payload> ST`
+ * - `ESC ] 9;4;<state>;;<payload> ST` (indeterminate)
+ */
+export declare const OSC_PROGRESS_PREFIX = "\u001B]9;4;";
+/** String Terminator (ST): `ESC \\` */
+export declare const OSC_PROGRESS_ST = "\u001B\\";
+/** Bell (BEL): `0x07` */
+export declare const OSC_PROGRESS_BEL = "\u0007";
+/** C1 String Terminator (ST): `0x9c` */
+export declare const OSC_PROGRESS_C1_ST = "\u009C";
+/** How to terminate the OSC sequence when emitting. */
+export type OscProgressTerminator = 'st' | 'bel';
+export interface OscProgressSupportOptions {
+    /** Force support on/off, overriding env heuristics. */
+    force?: boolean;
+    disabled?: boolean;
+    /** Name of env var which disables OSC progress when set to `"1"`. */
+    disableEnvVar?: string;
+    /** Name of env var which forces OSC progress when set to `"1"`. */
+    forceEnvVar?: string;
+}
+export interface OscProgressOptions extends OscProgressSupportOptions {
+    /**
+     * Extra payload appended to the OSC sequence (many terminals ignore this; a few show it).
+     * Defaults to `"Working…"`. Sanitized to avoid control chars and terminators.
+     */
+    label?: string;
+    /**
+     * Target duration in ms for the internal `0 → 99%` ramp.
+     * The implementation never emits 100% by itself; completion is via `stop()`.
+     */
+    targetMs?: number;
+    /** Write function (defaults to `process.stderr.write`). */
+    write?: (data: string) => void;
+    /** Environment lookup (defaults to `process.env`). */
+    env?: NodeJS.ProcessEnv;
+    /** TTY flag (defaults to `process.stdout.isTTY`). */
+    isTty?: boolean;
+    /** When true, emit an indeterminate progress indicator (no percentage). */
+    indeterminate?: boolean;
+    /**
+     * Numeric OSC 9;4 state.
+     * - 0: clear/hide
+     * - 1: normal
+     * - 2: error
+     * - 3: indeterminate
+     * - 4: ambiguous (paused/warning depending on terminal)
+     */
+    state?: 1 | 2 | 4;
+    /** OSC terminator to use. `st` = ESC \\, `bel` = BEL. */
+    terminator?: OscProgressTerminator;
+}
+export interface OscProgressSequence {
+    /** Inclusive start index in the input string. */
+    start: number;
+    /** Exclusive end index in the input string. */
+    end: number;
+    /** Raw substring that matched. */
+    raw: string;
+    /** Which terminator was encountered. */
+    terminator: 'st' | 'bel' | 'c1st';
+}
+/**
+ * Sanitizes a label/payload so it can't break the surrounding OSC sequence.
+ * Removes escape chars and common OSC terminators; trims whitespace.
+ */
+export declare function sanitizeLabel(label: string): string;
+/**
+ * Best-effort check whether OSC 9;4 progress output is likely to work.
+ *
+ * Default heuristics:
+ * - requires `isTty === true`
+ * - enables for Ghostty (`TERM_PROGRAM=ghostty*`), WezTerm (`TERM_PROGRAM=wezterm*`), Windows Terminal (`WT_SESSION`)
+ *
+ * Override knobs:
+ * - `options.force` / `options.disabled`
+ * - `options.forceEnvVar` / `options.disableEnvVar` (expects value `"1"`)
+ */
+export declare function supportsOscProgress(env?: NodeJS.ProcessEnv, isTty?: boolean, options?: OscProgressSupportOptions): boolean;
+/**
+ * Finds OSC 9;4 progress sequences inside an arbitrary string.
+ *
+ * Supports three terminators:
+ * - ST (`ESC \\`)
+ * - BEL (`0x07`)
+ * - C1 ST (`0x9c`)
+ *
+ * Unterminated sequences are ignored (use `stripOscProgress` if you want to drop them).
+ */
+export declare function findOscProgressSequences(text: string): OscProgressSequence[];
+/**
+ * Removes OSC 9;4 progress sequences from `text`.
+ *
+ * Behavior:
+ * - strips sequences terminated by ST/BEL/C1 ST
+ * - if a sequence is unterminated, it is removed until end-of-string
+ */
+export declare function stripOscProgress(text: string): string;
+/**
+ * Convenience helper:
+ * - if `keepOsc` is true, returns the input unchanged (useful when writing to a TTY)
+ * - otherwise, strips OSC 9;4 sequences (useful for logs/snapshots)
+ */
+export declare function sanitizeOscProgress(text: string, keepOsc: boolean): string;
+/**
+ * Emits a terminal progress indicator using OSC 9;4 and returns `stop()`.
+ *
+ * Notes:
+ * - no-op when `supportsOscProgress(...)` is false
+ * - determinate mode ramps `0% → 99%` on a timer; `stop()` clears progress
+ * - indeterminate mode emits `state=3` and `stop()` clears progress
+ */
+export declare function startOscProgress(options?: OscProgressOptions): () => void;

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "osc-progress",
+  "version": "0.1.0",
+  "description": "Tiny TypeScript helper for OSC 9;4 terminal progress sequences.",
+  "license": "MIT",
+  "author": "Peter Steinberger",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/steipete/osc-progress.git"
+  },
+  "homepage": "https://github.com/steipete/osc-progress#readme",
+  "bugs": {
+    "url": "https://github.com/steipete/osc-progress/issues"
+  },
+  "keywords": [
+    "osc",
+    "terminal",
+    "progress",
+    "cli",
+    "ghostty",
+    "wezterm",
+    "windows-terminal"
+  ],
+  "type": "module",
+  "main": "./dist/esm/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/esm/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "sideEffects": false,
+  "packageManager": "pnpm@10.25.0",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepare": "pnpm build",
+    "prepack": "pnpm build",
+    "prepublishOnly": "pnpm check",
+    "typecheck": "tsc -p tsconfig.build.json --noEmit",
+    "format": "biome format --write .",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "test": "pnpm build && vitest run",
+    "test:coverage": "pnpm build && vitest run --coverage",
+    "check": "pnpm lint && pnpm test:coverage"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.10",
+    "@types/node": "^25.0.3",
+    "@vitest/coverage-v8": "^4.0.16",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16"
+  }
+}