node-tmux-cli 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CassianKnoth
+
+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,178 @@
+# configurable `tmux` with `node.js` CLI
+
+Create (or interact with) your `tmux` sessions quick and easy, again and again from one simple config file!
+
+## 📚 Contents
+
+- [Quick start](#quick-start)
+- [How it works](#how-it-works)
+- [Development](#️-development)
+
+## 👉 Quick start
+
+### Requirements
+
+This project was developed with
+
+- [node](https://nodejs.org/en) version 22.18.0
+- [tmux](https://github.com/tmux/tmux/wiki) version 3.5a
+
+### Getting started
+
+Install the `node-tmux` CLI globally:
+
+```bash
+npm install -g node-tmux
+```
+
+Create a config file:
+
+```bash
+node-tmux init
+```
+
+Edit the config file to your liking and run:
+
+```bash
+node-tmux
+```
+
+### Default vs custom config file
+
+`node-tmux init` will create a `.node-tmux` folder with a `node-tmux-config.json` file in your home directory. Running `node-tmux` will look for that as a default config file (with that name!). You can also run `node-tmux init --local` (with `-l`/`--local` flag) which creates a `node-tmux-config.json` file in your current directory. Whether you create such a config file that way or completely on your own, you can run any such config by passing its path with the `-c`/`--config` flag:
+
+```bash
+node-tmux --config ./some/directory/node-tmux-config.json
+```
+
+These files you can also name whatever you desire:
+
+```bash
+node-tmux --config ./some/directory/myConfig.json
+```
+
+## 🔬 How it works
+
+Look at this simple config template:
+
+```json
+{
+	"$schema": "../schema/schema.json",
+	"shell": "bash", // choose bash or zsh for running commands
+	"sessions": {
+		"mySession": [
+			{
+				"name": "myWindow",
+				"workspacePath": "/absolute/path/to/my-awesome-project",
+				"additionalPanes": [
+					{
+						"name": "server"
+					},
+					{
+						"name": "watcher",
+						"subPath": "subfolder",
+						// results in /absolute/path/to/my-awesome-project/subfolder
+						"command": "echo HELLO FROM WATCHER" // runs in the shell you configured above
+					}
+				]
+			}
+		]
+	}
+}
+```
+
+You can list any number of `tmux`-session configs under `sessions`. The porperty key (e. g. `mySession`) is the session name and holds a list of windows which can also hold a list of panes. Each window requires a `name` and a `workspacePath` (where the window's default pane should be initialized). Next to the default pane, the `additionalPanes` require a `name` and _optionally_ a `subPath` (if it should not be initalized at the window's `workspacePath`, which is the default) and also _optionally_ a `command` which should be run at creation (e. g. `echo hello world` or maybe `npm run build:watch`). This command will be run in `bash` or `zsh` depending what you configure as `shell`.
+
+If you run the above default config file (e. g. as default config with just `node-tmux` after `node-tmux init`) you will see something like this:
+
+<img src="./assets/config-selection.png">
+
+If you then provide a valid key, three scenarios are possible:
+
+- No session with that config is currently running
+- A session with that config _is_ currently running in a _detached_ state
+- A session with that config _is_ currently running in an _attached_ state
+
+If no session is running, you could start it now:
+
+<img src="./assets/start-session.png">
+
+Every new session starts in _detached_ state.
+
+Now you will have more options to deal with the session:
+
+<img src="./assets/options.png">
+
+> 💡 Notice how the states will be indicated in the session list already
+
+- attach --> attaches the session to your current terminal
+- restart --> restarts the session
+- destroy --> kills the session
+- other --> deal with another session
+- exit --> exit CLI
+
+> 💡 It is sufficient to type the first letter of each option. Also each option comes with confirmation.
+
+Let's attach the session and look at the result in `tmux`:
+
+<img src="./assets/tmux.png">
+
+Compare this to the config: You can see that the session consists of one window (see `mySession-myWindow` at the bottom left. You can use or ignore the default window next to it). For `myWindow` two `additionalPanes` were configured, thus the window was split two times, resulting in three panes:
+
+- A default pane
+- The configured pane named "server"
+- The configured pane named "watcher"
+  - The configured command was executed with the configured shell
+
+You could actually run the CLI inside the `tmux`-session again:
+
+<img src="./assets/attached.png">
+
+The session is now correctly marked as _attached_ and the `[a]ttach` option is gone. This is to help keeping things organized – if the session is attached somewhere already, use that.
+
+> 💡 You can technically attach a _detached_ session inside a running `tmux`-session, but that might take on confusing inception like nesting. Do as you please.
+
+## 🛠️ Development
+
+1. 📄 Clone the project
+
+- HTTPS:
+
+```bash
+git clone https://github.com/CassianKnoth/configurable-tmux-node.git
+```
+
+- SSH:
+
+```bash
+git clone git@github.com:CassianKnoth/configurable-tmux-node.git
+```
+
+2. ➡️ Navigate into project
+
+```bash
+cd configurable-tmux-node
+```
+
+3. 🏗️ Build the project
+
+```bash
+npm run build
+```
+
+4. 🚀 Run CLI
+
+```bash
+npm run dev
+```
+
+> 💡 Or directly `node dist/index.js` with or wothout arguments/flags
+
+## 📈 Improvements?
+
+- Reusable config snippets
+  - Reference windows or panes from a `snippets` list if you need the same ones in multiple session configs
+
+- Configure shell per pane instead of globally
+
+- Delete default window

package/dist/config/schema/schema.json

@@ -0,0 +1,82 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "additionalProperties": false,
+    "definitions": {
+        "SessionConfigurations": {
+            "$ref": "#/definitions/__type"
+        },
+        "Shell": {
+            "enum": [
+                "bash",
+                "zsh"
+            ],
+            "type": "string"
+        },
+        "__type": {
+            "additionalProperties": {
+                "items": {
+                    "additionalProperties": false,
+                    "properties": {
+                        "additionalPanes": {
+                            "description": "Optional: Besides the given root, what other panes should be horizontally split next to it in the same window.",
+                            "items": {
+                                "additionalProperties": false,
+                                "properties": {
+                                    "command": {
+                                        "description": "Optional: Command that should be run in ths pane",
+                                        "type": "string"
+                                    },
+                                    "name": {
+                                        "description": "This will be used together with the window name",
+                                        "type": "string"
+                                    },
+                                    "subPath": {
+                                        "description": "Optional: Opens the pane at the given relative path which will be appended to the `workSpacePath`",
+                                        "type": "string"
+                                    }
+                                },
+                                "required": [
+                                    "name"
+                                ],
+                                "type": "object"
+                            },
+                            "type": "array"
+                        },
+                        "name": {
+                            "description": "Name of the tmux window. This will be used as the prefix for window and pane names.",
+                            "type": "string"
+                        },
+                        "workspacePath": {
+                            "description": "Absolute path to workspace root.",
+                            "type": "string"
+                        }
+                    },
+                    "required": [
+                        "name",
+                        "workspacePath"
+                    ],
+                    "type": "object"
+                },
+                "type": "array"
+            },
+            "type": "object"
+        }
+    },
+    "properties": {
+        "$schema": {
+            "type": "string"
+        },
+        "sessions": {
+            "$ref": "#/definitions/SessionConfigurations"
+        },
+        "shell": {
+            "$ref": "#/definitions/Shell"
+        }
+    },
+    "required": [
+        "sessions",
+        "shell"
+    ],
+    "type": "object"
+}
+

package/dist/config/template/node-tmux-config.json

@@ -0,0 +1,22 @@
+{
+	"$schema": "https://unpkg.com/node-tmux@0.2.0/dist/config/schema/schema.json",
+	"shell": "bash",
+	"sessions": {
+		"mySession": [
+			{
+				"name": "myWindow",
+				"workspacePath": "/absolute/path/to/my-awesome-project",
+				"additionalPanes": [
+					{
+						"name": "server"
+					},
+					{
+						"name": "watcher",
+						"subPath": "src",
+						"command": "echo HELLO FROM WATCHER"
+					}
+				]
+			}
+		]
+	}
+}

package/dist/index.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+import { styleText } from 'node:util';
+import { renderState } from './util/state/render-state.js';
+import { exitOut } from './util/exit.js';
+import { printLineSeparator } from './util/layout/line-separator.js';
+import { transition } from './util/state/transition.js';
+import { getConfig } from './util/config/get-config.js';
+import { parseCLiArgs } from './util/commands/parser/parse-cli-args.js';
+import { handleInit } from './util/commands/handler/handle-init.js';
+import { DEFAULT_CONFIG_FILE_PATH } from './util/config/config-paths.js';
+import { handleHelp } from './util/commands/handler/handle-help.js';
+printLineSeparator();
+console.log('🚀 tmux ACTiON!');
+const parsedArgs = parseCLiArgs();
+// handle everything else than 'run'
+switch (parsedArgs.command) {
+    case 'init':
+        handleInit(parsedArgs.local);
+        break;
+    case 'help':
+        handleHelp();
+        break;
+}
+printLineSeparator();
+console.log('⏳ Getting config file path...');
+const configFilePath = parsedArgs.configPath ?? DEFAULT_CONFIG_FILE_PATH;
+const config = getConfig(configFilePath);
+// exit without configurations
+const configuredSessionNames = Object.keys(config.sessions);
+if (configuredSessionNames.length < 1) {
+    console.log(styleText('red', '❌ Found no configured sessions'));
+    console.log(styleText('cyan', '➡️ Please provide at least 1 configuration in config.ts'));
+    exitOut();
+    // EXiT
+}
+export const { shell: confiuredShell, sessions: configuredSessions } = config;
+let context = {
+    sessionState: 'NO_CONFIG',
+    sessionName: '',
+};
+while (true) {
+    if (context.sessionState === 'EXIT') {
+        exitOut();
+    }
+    // render state
+    renderState(context);
+    // handle state transition
+    const newContext = await transition(context);
+    // set new state
+    context = newContext;
+}

package/dist/util/commands/handler/handle-help.js

@@ -0,0 +1,47 @@
+import { exitOut } from '../../exit.js';
+import { printLineSeparator } from '../../layout/line-separator.js';
+import { printPaddedLine } from '../../layout/print-padded-line.js';
+const validCommands = [
+    {
+        name: 'node-tmux',
+        description: 'Runs the CLI with default config file',
+    },
+    {
+        name: 'init',
+        description: 'Initializes a node-tmux-config.json file in the home directory under .node-tmux',
+        flags: [
+            {
+                name: '-l / --local',
+                description: 'Creates a node-tmux-config.json in the current directory instead of the home directory',
+            },
+        ],
+    },
+    {
+        name: '-c / --config',
+        description: 'Allows you to pass any path to a config file, e. g. "node-tmux -c ./path/to/config.json"',
+    },
+    {
+        name: '-h / --help',
+        description: 'Prints this reference',
+    },
+];
+export const handleHelp = () => {
+    printLineSeparator();
+    console.log('📚 These references might help you:');
+    console.log('\n');
+    validCommands.forEach((command) => {
+        console.group();
+        printPaddedLine(command.name, command.description);
+        if (command.flags) {
+            console.log('🚩 (flags)');
+            command.flags.forEach((flag) => {
+                console.group();
+                printPaddedLine(flag.name, flag.description);
+                console.groupEnd();
+            });
+        }
+        console.groupEnd();
+        console.log('\n');
+    });
+    exitOut();
+};

package/dist/util/commands/handler/handle-init.js

@@ -0,0 +1,29 @@
+import path from 'node:path';
+import fs from 'fs';
+import { printLineSeparator } from '../../layout/line-separator.js';
+import { styleText } from 'node:util';
+import { exitOut } from '../../exit.js';
+import { DEFAULT_CONFIG_FILE_NAME, DEFAULT_CONFIG_FILE_PATH, DEFAULT_CONFIG_HOME_DIR, TEMPLATE_FILE, } from '../../config/config-paths.js';
+export const handleInit = (local) => {
+    printLineSeparator();
+    // check local
+    const configFilePath = local
+        ? path.join(process.cwd(), DEFAULT_CONFIG_FILE_NAME)
+        : DEFAULT_CONFIG_FILE_PATH;
+    // check if file exists
+    console.log(`👀 Looking for config file at ${configFilePath} ...`);
+    if (fs.existsSync(configFilePath)) {
+        console.log(styleText('yellow', 
+        // double space due to emoji consisting of two characters
+        `⚠️  Config file already exists at ${configFilePath}.`));
+        exitOut();
+    }
+    // double space due to emoji consisting of two characters
+    console.log(`ℹ️  Found no config file at ${configFilePath}`);
+    console.log(`⏳ Initializing config file at ${configFilePath} ...`);
+    if (!local) {
+        fs.mkdirSync(DEFAULT_CONFIG_HOME_DIR, { recursive: true });
+    }
+    fs.copyFileSync(TEMPLATE_FILE, configFilePath);
+    exitOut();
+};

package/dist/util/commands/parser/is-initializer.js

@@ -0,0 +1,4 @@
+export const initializers = ['init', '-c', '--config', '-h', '--help'];
+export const isInitializer = (value) => {
+    return initializers.includes(value);
+};

package/dist/util/commands/parser/parse-cli-args.js

@@ -0,0 +1,32 @@
+import { argv } from 'node:process';
+import { isInitializer } from './is-initializer.js';
+import { parseInit } from './parse-init.js';
+import { parseConfig } from './parse-config.js';
+import { styleText } from 'node:util';
+export const parseCLiArgs = () => {
+    const rawArgs = argv.slice(2);
+    const firstArg = rawArgs[0];
+    // ready to run immedeately
+    if (!firstArg) {
+        return { command: 'run' };
+    }
+    // catch unknown args
+    if (!isInitializer(firstArg)) {
+        console.log(styleText('red', `❌ Command not found: ${firstArg}`));
+        return { command: 'help' };
+    }
+    // or with run with (presumably) path argument
+    // if (!isInitializer(firstArg)) {
+    // 	return { command: 'run', configPath: firstArg };
+    // }
+    switch (firstArg) {
+        case 'init':
+            return parseInit(rawArgs[1]);
+        case '-c':
+        case '--config':
+            return parseConfig(rawArgs[1]);
+        default:
+            // help is the only option left
+            return { command: 'help' };
+    }
+};

package/dist/util/commands/parser/parse-config.js

@@ -0,0 +1,9 @@
+import { styleText } from 'node:util';
+export const parseConfig = (input) => {
+    if (!input) {
+        console.log(styleText('red', `❌ Missing config file path`));
+        console.log(styleText('cyan', `➡️ Please provide a path to a config file or run node-tmux without any flags to use the default config file instead`));
+        return { command: 'help' };
+    }
+    return { command: 'run', configPath: input };
+};

package/dist/util/commands/parser/parse-init.js

@@ -0,0 +1,12 @@
+import { styleText } from 'node:util';
+export const parseInit = (input) => {
+    if (!input) {
+        return { command: 'init' };
+    }
+    const isLocal = ['-l', '--local'].includes(input);
+    if (isLocal) {
+        return { command: 'init', local: true };
+    }
+    console.log(styleText('red', `❌ Unknown argument: ${input}`));
+    return { command: 'help' };
+};

package/dist/util/config/config-paths.js

@@ -0,0 +1,9 @@
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import os from 'node:os';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+export const DEFAULT_CONFIG_HOME_DIR = path.join(os.homedir(), '.node-tmux');
+export const DEFAULT_CONFIG_FILE_NAME = 'node-tmux-config.json';
+export const DEFAULT_CONFIG_FILE_PATH = path.join(DEFAULT_CONFIG_HOME_DIR, DEFAULT_CONFIG_FILE_NAME);
+export const TEMPLATE_FILE = path.join(__dirname, '../../config/template/', DEFAULT_CONFIG_FILE_NAME);

package/dist/util/config/get-config.js

@@ -0,0 +1,32 @@
+import fs from 'fs';
+import schema from '../../config/schema/schema.json' with { type: 'json' };
+import { createRequire } from 'node:module';
+import { printLineSeparator } from '../layout/line-separator.js';
+import { styleText } from 'node:util';
+const require = createRequire(import.meta.url);
+const Ajv = require('ajv');
+export const ajv = new Ajv({ allErrors: true });
+const validate = ajv.compile(schema);
+export const getConfig = (configFilePath) => {
+    printLineSeparator();
+    console.log(`👀 Looking for config file at ${configFilePath} ...`);
+    if (!fs.existsSync(configFilePath)) {
+        console.log(styleText('red', `❌ Config file not found: ${configFilePath}`));
+        console.log(styleText('cyan', 
+        // double space due to emoji consisting of two characters
+        '➡️  Run `node-tmux init` to create one, or use -c or --config flag to specify a path'));
+        process.exit(1);
+    }
+    const raw = JSON.parse(fs.readFileSync(configFilePath, 'utf-8'));
+    if (!validate(raw)) {
+        console.error('Invalid node-tmux config:');
+        for (const err of validate.errors ?? []) {
+            console.error(`- ${err.instancePath} ${err.message}`);
+        }
+        process.exit(1);
+    }
+    console.log(
+    // double space due to emoji consisting of two characters
+    styleText('green', `⚙️  Found valid config file at ${configFilePath}`));
+    return raw;
+};

package/dist/util/config/init.js

@@ -0,0 +1,5 @@
+import fs from 'node:fs';
+import path from 'node:path';
+export const init = (creationPath) => {
+    fs.copyFileSync(path.join(__dirname, 'templates/config.json'), creationPath);
+};

package/dist/util/config/list-configuration.js

@@ -0,0 +1,21 @@
+import { styleText } from 'node:util';
+import { configuredSessions } from '../../index.js';
+import { hasTmuxSession } from '../tmux/has-session.js';
+import { isTmuxAttached } from '../tmux/is-attached.js';
+export const listConfigurations = () => {
+    const configuredSessionNames = Object.keys(configuredSessions);
+    // double space due to emoji consisting of two characters
+    console.log('ℹ️  Available configurations:');
+    configuredSessionNames.forEach((configuredSessionName) => {
+        const hasSession = hasTmuxSession(configuredSessionName);
+        if (hasSession) {
+            const isAttached = isTmuxAttached(configuredSessionName);
+            const color = isAttached ? 'green' : 'yellow';
+            const suffix = isAttached ? '(attached)' : '(detached)';
+            console.log(styleText(color, ` - ${configuredSessionName} ${suffix}`));
+        }
+        else {
+            console.log(` - ${configuredSessionName}`);
+        }
+    });
+};

package/dist/util/exit.js

@@ -0,0 +1,4 @@
+export const exitOut = () => {
+    console.log('👋 exiting...');
+    process.exit(0);
+};

package/dist/util/format-compound-path.js

@@ -0,0 +1,12 @@
+const parsePath = (path, pattern, replacement) => {
+    const parsedPath = path.replace(pattern, replacement);
+    return parsedPath;
+};
+export const formatCompoundPath = (basePath, subPath) => {
+    const leadingSlashRegex = /^\/+/;
+    const trailingSlashRegex = /\/+$/;
+    const parsedBasePath = parsePath(basePath, trailingSlashRegex, '');
+    const parsedSubPath = parsePath(subPath, leadingSlashRegex, '');
+    const compoundPath = `${parsedBasePath}/${parsedSubPath}`;
+    return compoundPath;
+};

package/dist/util/layout/line-separator.js

@@ -0,0 +1,3 @@
+export const printLineSeparator = () => {
+    console.log('----- ------- -----');
+};

package/dist/util/layout/pad-text.js

@@ -0,0 +1,3 @@
+export const padText = (text) => {
+    return text.padEnd(24);
+};

package/dist/util/layout/print-padded-line.js

@@ -0,0 +1,4 @@
+import { padText } from './pad-text.js';
+export const printPaddedLine = (left, right) => {
+    console.log(`${padText(left)} ${right}`);
+};

package/dist/util/state/fresh-state.js

@@ -0,0 +1,4 @@
+export const freshState = {
+    sessionState: 'NO_CONFIG',
+    sessionName: '',
+};

package/dist/util/state/handler/handle-no-config-state.js

@@ -0,0 +1,54 @@
+import { styleText } from 'node:util';
+import { choices } from '../../user-input/user-choice/choices.js';
+import { getUserInput } from '../../user-input/get-user-input.js';
+import { hasTmuxSession } from '../../tmux/has-session.js';
+import { isTmuxAttached } from '../../tmux/is-attached.js';
+import { tmuxStartSession } from '../../tmux/start/start-session.js';
+import { handleWithConfirmation } from '../../user-input/user-choice/handle-choice-with-confirmation.js';
+import { configuredSessions } from '../../../index.js';
+import { userConfirmation } from '../../user-input/user-confirmation.js';
+export const handleNoConfigState = async (currentContext) => {
+    // get user input
+    const userInput = await getUserInput('🔑 Session-configuration key or [e]xit: ');
+    // handle exit
+    if (choices.exit.regex.test(userInput)) {
+        const newContext = await handleWithConfirmation(choices.exit, currentContext);
+        return newContext;
+    }
+    // handle other input
+    console.log(`👀 Looking for session "${userInput}"...`);
+    const configuration = configuredSessions[userInput];
+    // - invalid input
+    if (!configuration) {
+        console.log(styleText('red', `❌ "${userInput}" is not a valid configuration`));
+        console.log(styleText('cyan', 
+        // double space due to emoji consisting of two characters
+        `➡️  Check for typos, create it and then try again, or choose another`));
+        return { ...currentContext, sessionState: 'NO_CONFIG' };
+    }
+    const sessionName = userInput;
+    console.log(
+    // double space due to emoji consisting of two characters
+    styleText('green', `⚙️  Found configuration for "${sessionName}"`));
+    console.log(`🔍 Checking status of "${sessionName}"...`);
+    const hasSession = hasTmuxSession(sessionName);
+    // - attached / detached
+    if (hasSession) {
+        console.log(styleText('yellow', `🏃 Session "${sessionName}" is already running`));
+        const isAttached = isTmuxAttached(sessionName);
+        if (isAttached) {
+            return { sessionState: 'ATTACHED_SESSION', sessionName: sessionName };
+        }
+        else {
+            return { sessionState: 'DETACHED_SESSION', sessionName: sessionName };
+        }
+    }
+    // - start
+    console.log(`Status: Session "${sessionName}" is inactive`);
+    const confirmed = await userConfirmation(`Start session "${sessionName}?"`);
+    if (confirmed) {
+        tmuxStartSession(sessionName);
+        return { sessionState: 'DETACHED_SESSION', sessionName: sessionName };
+    }
+    return currentContext;
+};

package/dist/util/state/render-state.js

@@ -0,0 +1,24 @@
+import { styleText } from 'node:util';
+import { listConfigurations } from '../config/list-configuration.js';
+import { printLineSeparator } from '../layout/line-separator.js';
+export const renderState = async ({ sessionState, sessionName }) => {
+    printLineSeparator();
+    switch (sessionState) {
+        case 'NO_CONFIG':
+            console.log(styleText('yellow', 
+            // double space due to emoji consisting of two characters
+            '⚠️  Please provide a valid session-configuration key to start or interact with a session'));
+            break;
+        case 'DETACHED_SESSION':
+            console.log(
+            // double space due to emoji consisting of two characters
+            styleText('yellow', `⚠️  Session "${sessionName}" is running detached`));
+            break;
+        case 'ATTACHED_SESSION':
+            console.log(
+            // double space due to emoji consisting of two characters
+            styleText('yellow', `⚠️  Session "${sessionName}" is running attached`));
+            break;
+    }
+    listConfigurations();
+};

package/dist/util/state/transition.js

@@ -0,0 +1,30 @@
+import { printLineSeparator } from '../layout/line-separator.js';
+import { handleUserChoice } from '../user-input/user-choice/handle-user-choice.js';
+import { handleNoConfigState } from './handler/handle-no-config-state.js';
+export const transition = async (currentContext) => {
+    printLineSeparator();
+    let newContext = { ...currentContext, sessionState: 'EXIT' };
+    switch (currentContext.sessionState) {
+        case 'NO_CONFIG':
+            newContext = await handleNoConfigState(currentContext);
+            break;
+        case 'DETACHED_SESSION':
+            newContext = await handleUserChoice({
+                attach: true,
+                restart: true,
+                destroy: true,
+                other: true,
+                exit: true,
+            }, currentContext);
+            break;
+        case 'ATTACHED_SESSION':
+            newContext = await handleUserChoice({
+                restart: true,
+                destroy: true,
+                other: true,
+                exit: true,
+            }, currentContext);
+            break;
+    }
+    return newContext;
+};

package/dist/util/tmux/attach-session.js

@@ -0,0 +1,9 @@
+import { execFileSync } from 'node:child_process';
+import { printLineSeparator } from '../layout/line-separator.js';
+export const tmuxAttach = (sessionName) => {
+    printLineSeparator();
+    console.log(`📌 Attaching session "${sessionName}"`);
+    execFileSync('tmux', ['attach', '-t', sessionName], {
+        stdio: 'inherit',
+    });
+};

package/dist/util/tmux/destroy-session.js

@@ -0,0 +1,8 @@
+import { execSync } from 'node:child_process';
+import { printLineSeparator } from '../layout/line-separator.js';
+export const tmuxDestroySession = (sessionName) => {
+    printLineSeparator();
+    console.log(`💥 Destroying session "${sessionName}"...`);
+    execSync(`tmux kill-session -t ${sessionName}`);
+    console.log(`✅ Session "${sessionName}" was destroyed`);
+};

package/dist/util/tmux/has-session.js

@@ -0,0 +1,13 @@
+import { execSync } from 'node:child_process';
+/** Determines whether a given tmux session is running or not
+ * @param sessionName Name of the tmux session
+ */
+export const hasTmuxSession = (sessionName) => {
+    try {
+        execSync(`tmux has-session -t ${sessionName}`, { stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+};

package/dist/util/tmux/is-attached.js

@@ -0,0 +1,19 @@
+import { execSync } from 'node:child_process';
+/** Determines whether a given tmux session is attached or not
+ * @param sessionName Name of the tmux session
+ */
+export const isTmuxAttached = (sessionName) => {
+    const attached = execSync(`tmux display-message -p -t ${sessionName} "#{session_attached}"`)
+        .toString()
+        .trim();
+    return attached === '1';
+    // try {
+    // 	execSync(
+    // 		`tmux list-sessions -F "#{session_name} #{session_attached}" | awk -v name="${sessionName}" '$1 == name {print $2}'`,
+    // 		{ stdio: 'ignore' },
+    // 	);
+    // 	return true;
+    // } catch {
+    // 	return false;
+    // }
+};

package/dist/util/tmux/start/create-pane.js

@@ -0,0 +1,22 @@
+import { execSync } from 'node:child_process';
+import { formatCompoundPath } from '../../format-compound-path.js';
+import { confiuredShell } from '../../../index.js';
+export const createPane = (pane, paneIndex, windowIdentifier, basePath) => {
+    const paneName = pane.name;
+    const splitTarget = `${windowIdentifier}.${paneIndex}`;
+    const newPaneIdentifier = `${windowIdentifier}.${paneIndex + 1}`;
+    const path = pane.subPath
+        ? formatCompoundPath(basePath, pane.subPath)
+        : basePath;
+    console.log(`⏳ 🧩 Creating new Pane "${paneName}"`);
+    execSync(`tmux split-window -h -t ${splitTarget} -c ${path}`);
+    execSync(`tmux select-pane -t ${newPaneIdentifier} -T ${paneName}`);
+    console.log(`✅ Pane "${paneName}" was created`);
+    if (pane.command) {
+        console.log(`⏳ 🤖 Executing configured command in Pane "${paneName}"...`);
+        // replace double quotes because they can mess with shell execution
+        execSync(`tmux send-keys -t ${newPaneIdentifier} "${confiuredShell} -c '${pane.command.replace(/"/g, '\\"')}; exec ${confiuredShell}'" C-m`);
+        execSync(`tmux send-keys -t ${newPaneIdentifier} Enter`);
+        console.log(`✅ Command executed in Pane "${paneName}"`);
+    }
+};

package/dist/util/tmux/start/create-window.js

@@ -0,0 +1,27 @@
+import { execSync } from 'node:child_process';
+import { printLineSeparator } from '../../layout/line-separator.js';
+import { createPane } from './create-pane.js';
+export const createWindow = (window, windowIndex, sessionName) => {
+    printLineSeparator();
+    const windowName = `${sessionName}-${window.name}`;
+    // double space due to emoji consisting of two characters
+    console.log(`🏗️  Building "${windowName}"...`);
+    // double space due to emoji consisting of two characters
+    console.log(`⏳ 🖼️  Creating new Window "${windowName}"`);
+    execSync(`tmux new-window -t ${sessionName}:${windowIndex + 1} -n ${windowName} -c ${window.workspacePath}`);
+    console.log(`✅ Window "${windowName}" was created`);
+    const windowIdentifier = `${sessionName}:${windowName}`;
+    const originPaneIdentifier = `${windowIdentifier}.0`;
+    const originPaneName = 'origin';
+    console.log(`⏳ 🧩 Creating new Pane "${originPaneName}"...`);
+    execSync(`tmux select-pane -t ${originPaneIdentifier} -T ${originPaneName}`);
+    console.log(`✅ Pane "${originPaneName}" was created`);
+    if (window.additionalPanes) {
+        printLineSeparator();
+        // double space due to emoji consisting of two characters
+        console.log(`🏗️  Building additional Panes...`);
+        window.additionalPanes.forEach((pane, paneIndex) => {
+            createPane(pane, paneIndex, windowIdentifier, window.workspacePath);
+        });
+    }
+};

package/dist/util/tmux/start/start-session.js

@@ -0,0 +1,16 @@
+import { execSync } from 'node:child_process';
+import { printLineSeparator } from '../../layout/line-separator.js';
+import { createWindow } from './create-window.js';
+import { configuredSessions } from '../../../index.js';
+export const tmuxStartSession = (sessionName) => {
+    const configuredWindows = configuredSessions[sessionName];
+    if (!configuredWindows) {
+        throw new Error(`Internal: No configuration found for: ${sessionName}`);
+    }
+    printLineSeparator();
+    const initialWindowName = 'default';
+    console.log(`⏳ Creating new detached session "${sessionName}"...`);
+    execSync(`tmux new -d -s ${sessionName} -n ${initialWindowName} -c "$(pwd)"`);
+    console.log(`✅ Session "${sessionName}" was created`);
+    configuredWindows.forEach((window, windowIndex) => createWindow(window, windowIndex, sessionName));
+};

package/dist/util/user-input/get-user-input.js

@@ -0,0 +1,8 @@
+import * as readline from 'node:readline/promises';
+import { stdin as input, stdout as output } from 'node:process';
+export const getUserInput = async (prompt) => {
+    const rl = readline.createInterface({ input, output });
+    const userInput = await rl.question(prompt);
+    rl.close();
+    return userInput.trim();
+};

package/dist/util/user-input/user-choice/choices.js

@@ -0,0 +1,37 @@
+import { attachHandler } from './handler/attach-handler.js';
+import { destroyHandler } from './handler/destroy-handler.js';
+import { exitHandler } from './handler/exit-handler.js';
+import { otherHandler } from './handler/other-handler.js';
+import { restartHandler } from './handler/restart-handler.js';
+export const choices = {
+    attach: {
+        label: 'attach',
+        optionLabel: '[a]ttach',
+        regex: /a$|attach/i,
+        handler: attachHandler,
+    },
+    destroy: {
+        label: 'destroy',
+        optionLabel: '[d]estroy',
+        regex: /d$|destroy/i,
+        handler: destroyHandler,
+    },
+    restart: {
+        label: 'restart',
+        optionLabel: '[r]estart',
+        regex: /r$|restart/i,
+        handler: restartHandler,
+    },
+    other: {
+        label: 'other',
+        optionLabel: '[o]ther',
+        regex: /o$|other/i,
+        handler: otherHandler,
+    },
+    exit: {
+        label: 'exit',
+        optionLabel: '[e]xit',
+        regex: /e$|exit/i,
+        handler: exitHandler,
+    },
+};

package/dist/util/user-input/user-choice/get-parsed-available-options.js

@@ -0,0 +1,17 @@
+import { choices } from './choices.js';
+function isKeyOf(key, obj) {
+    return key in obj;
+}
+export const getParsedAvailableOptions = (availableChoices) => {
+    const parsedAvailableOptions = Object.keys(availableChoices)
+        .map((choiceKey) => {
+        if (isKeyOf(choiceKey, choices)) {
+            return choices[choiceKey];
+        }
+        else {
+            return undefined;
+        }
+    })
+        .filter((choice) => choice !== undefined);
+    return parsedAvailableOptions;
+};

package/dist/util/user-input/user-choice/handle-choice-with-confirmation.js

@@ -0,0 +1,9 @@
+import { getUserInput } from '../get-user-input.js';
+export const handleWithConfirmation = async (choice, currentContext) => {
+    const userInput = await getUserInput(`👉 ${choice.label}? [Y/n]: `);
+    const confirmed = !/n$|no/i.test(userInput);
+    const newContext = confirmed
+        ? choice.handler(currentContext)
+        : currentContext;
+    return newContext;
+};

package/dist/util/user-input/user-choice/handle-user-choice.js

@@ -0,0 +1,28 @@
+import { listChoiceLabels } from './list-choice-labels.js';
+import { getUserInput } from '../get-user-input.js';
+import { getParsedAvailableOptions } from './get-parsed-available-options.js';
+import { styleText } from 'node:util';
+import { handleWithConfirmation } from './handle-choice-with-confirmation.js';
+/**
+ * Present the user with a set of choices and handle the input accordingly.
+ *
+ * @param availableChoices Opt in parameter for available choices.
+ * Value is always `true`, the property just needs to be set. All omitted properties will not be listed as choice.
+ *
+ * Choices: `attach`, `destroy`, `restart`, `other`, 'exit'
+ */
+export const handleUserChoice = async (availableChoices, currentContext) => {
+    const parsedAvailableOptions = getParsedAvailableOptions(availableChoices);
+    const question = `👉 The choice is yours: ${listChoiceLabels(parsedAvailableOptions)}`;
+    const userInput = await getUserInput(question);
+    const matchedOption = parsedAvailableOptions.find((option) => {
+        return option.regex.test(userInput);
+    });
+    // loop until valid input
+    if (!matchedOption) {
+        console.log(styleText('red', '❌ Invalid input, try again...'));
+        return currentContext;
+    }
+    const newContext = await handleWithConfirmation(matchedOption, currentContext);
+    return newContext;
+};

package/dist/util/user-input/user-choice/handler/attach-handler.js

@@ -0,0 +1,8 @@
+import { tmuxAttach } from '../../../tmux/attach-session.js';
+export const attachHandler = (currentContext) => {
+    if (!currentContext) {
+        throw new Error('Internal: No currentContext provided');
+    }
+    tmuxAttach(currentContext.sessionName);
+    return { ...currentContext, sessionState: 'EXIT' };
+};

package/dist/util/user-input/user-choice/handler/destroy-handler.js

@@ -0,0 +1,9 @@
+import { freshState } from '../../../state/fresh-state.js';
+import { tmuxDestroySession } from '../../../tmux/destroy-session.js';
+export const destroyHandler = (currentContext) => {
+    if (!currentContext) {
+        throw new Error('Internal: No currentContext provided');
+    }
+    tmuxDestroySession(currentContext.sessionName);
+    return freshState;
+};

package/dist/util/user-input/user-choice/handler/exit-handler.js

@@ -0,0 +1,3 @@
+export const exitHandler = () => {
+    return { sessionState: 'EXIT', sessionName: '' };
+};

package/dist/util/user-input/user-choice/handler/other-handler.js

@@ -0,0 +1,4 @@
+import { freshState } from '../../../state/fresh-state.js';
+export const otherHandler = () => {
+    return freshState;
+};

package/dist/util/user-input/user-choice/handler/restart-handler.js

@@ -0,0 +1,13 @@
+import { tmuxDestroySession } from '../../../tmux/destroy-session.js';
+import { tmuxStartSession } from '../../../tmux/start/start-session.js';
+export const restartHandler = (currentContext) => {
+    if (!currentContext) {
+        throw new Error('Internal: No currentContext provided');
+    }
+    const sessionName = currentContext.sessionName;
+    // double space due to emoji consisting of two characters
+    console.log(`🪃  Restarting session "${sessionName}"`);
+    tmuxDestroySession(sessionName);
+    tmuxStartSession(sessionName);
+    return { ...currentContext, sessionState: 'DETACHED_SESSION' };
+};

package/dist/util/user-input/user-choice/list-choice-labels.js

@@ -0,0 +1,12 @@
+export const listChoiceLabels = (choiceList) => {
+    if (!choiceList[0]) {
+        return '';
+    }
+    let choiceLabelList = choiceList[0].optionLabel;
+    const separator = ', ';
+    choiceList
+        .slice(1)
+        .forEach((choice) => (choiceLabelList = choiceLabelList + separator + choice.optionLabel));
+    choiceLabelList = choiceLabelList + ': ';
+    return choiceLabelList;
+};

package/dist/util/user-input/user-confirmation.js

@@ -0,0 +1,11 @@
+import { getUserInput } from './get-user-input.js';
+/**
+ * Prompts the user for yes/no confirmation
+ * @param prompt Will be presented to the user as `👉 ${prompt} [Y/n]: `
+ * @example "Confirm?" --> `👉 Confirm? [Y/n]: `
+ */
+export const userConfirmation = async (prompt) => {
+    const userInput = await getUserInput(`👉 ${prompt} [Y/n]: `);
+    const confirmed = !/n$|no/i.test(userInput);
+    return confirmed;
+};

package/package.json

@@ -0,0 +1,33 @@
+{
+	"name": "node-tmux-cli",
+	"version": "0.2.0",
+	"description": "",
+	"main": "index.js",
+	"type": "module",
+	"files": [
+		"dist"
+	],
+	"bin": {
+		"node-tmux-cli": "dist/index.js"
+	},
+	"scripts": {
+		"schema:generate": "rm -rf ./src/config/schema/schema.json && typescript-json-schema tsconfig.json NodeTmuxConfig --topRef --aliasRefs --noExtraProps --required > ./src/config/schema/schema.json",
+		"schema:validate": "node .github/scripts/validate-schema.js",
+		"prebuild": "npm run schema:generate",
+		"build": "rm -rf dist && tsc && cp -r ./src/config dist/ && npm run build:template",
+		"build:template": "node scripts/build-template.js",
+		"postbuild": "chmod +x dist/index.js",
+		"dev": "node dist/index.js"
+	},
+	"keywords": [],
+	"author": "",
+	"license": "MIT",
+	"devDependencies": {
+		"@types/node": "^25.0.8",
+		"typescript": "^5.9.3",
+		"typescript-json-schema": "^0.67.1"
+	},
+	"dependencies": {
+		"ajv": "^8.17.1"
+	}
+}