README: refresh to match current project state — add build/getting-started section, supported platforms, shipped features (script subcommand, pluggable consoles, runtime.cmd, static runtime support, help system), update missing/unripe sections, add documentation pointers, rename n/new->newns and d/new->newdir
2023-08 Note: this is **alpha** level software and still highly experimental.
Version 0.11.0 (2026-07) — this is **alpha** level software and still highly experimental. See `CHANGELOG.md` for recent changes.
### Supported Platforms
- Tcl 8.6+ required; Tcl 9.0 and 9.1 supported.
- Primary target: Windows (win32-x86_64). Linux, macOS, and FreeBSD are secondary targets.
### Getting Started
The project uses a Tcl-based build system (`src/make.tcl`). From the project root:
```
# Fetch a suitable Tcl runtime (cross-platform polyglot wrapper — runs from bash, powershell, or cmd.exe)
./bin/runtime.cmd fetch
# Build modules and libraries into the project root
tclsh src/make.tcl packages
# Full build (modules + libraries + VFS + binaries)
tclsh src/make.tcl project
```
See `src/README.md` for detailed build instructions and `bin/AGENTS.md` for the runtime manager.
For evaluating uncommitted source without a full build, a built executable can run directly against the source tree:
```
<punkexe> src shell
```
### Features
### Features
- default ansi color output - toggle with 'colour on' and 'colour off' (or set NO_COLOR environment variable)
- default ansi color output - toggle with 'colour on' and 'colour off' (or set NO_COLOR environment variable)
@ -70,32 +97,49 @@ BSD license
with colourised indication of type such as proc,alias,ensemble,oo object,oo class,imported,exported where possible.
with colourised indication of type such as proc,alias,ensemble,oo object,oo class,imported,exported where possible.
(renamed aliases and builtins and commands loaded from binaries will appear unmarked)
(renamed aliases and builtins and commands loaded from binaries will appear unmarked)
- `nn/` - move up one namespace towards root namespace '::' analogous to `cd ..` (alias `::/`)
- `nn/` - move up one namespace towards root namespace '::' analogous to `cd ..` (alias `::/`)
- `n/new <somename>` - create a child namespace called 'somename' and switch to it in one operation. (alias `:/new`)
- `newns <somename>` - create a child namespace called 'somename' and switch to it in one operation. (alias `:/new`)
- cross-platform alternative to cd & ls/dir without invoking child processes. Display colourised listing of dirs and folders - with vfs indication.
- cross-platform alternative to cd & ls/dir without invoking child processes. Display colourised listing of dirs and folders - with vfs indication.
- `d/` - list current directory (alias `./`)
- `d/` - list current directory (alias `./`)
also `d/ <globpattern>` to restrict output
also `d/ <globpattern>` to restrict output
- `d/ <subdir>` - switch to subdir and list contents in one operation
- `d/ <subdir>` - switch to subdir and list contents in one operation
- `dd/` - move up one directory and output listing. Roughly equivalent to `cd ..` followed by dir or ls (alias `../`)
- `dd/` - move up one directory and output listing. Roughly equivalent to `cd ..` followed by dir or ls (alias `../`)
- `d/new <folder>` - create a child directory and switch to it in one operation. (alias `./new <folder>`)
- `newdir <folder>` - create a child directory and switch to it in one operation.
- `<punkexe> script` subcommand for reliable non-interactive script execution:
- `punkexe script <file.tcl> ?args?` — runs a script file with conventional `::argv0`/`::argv`
- `commands | punkexe script` — runs piped stdin commands and exits at EOF (no trailing `exit` needed)
- Honest exit codes (0 success, 1 error with errorInfo on stderr); no shellfilter transforms or logging side effects.
- `lib:<name>` resolution for scriptlib scripts: `punkexe script lib:hello` or bare `punkexe lib:hello`
- pluggable console backends: the REPL can run against non-detectable terminal-like devices via `::opunk::Console` subclasses (ssh-channel, tk-widget, test-double), with size, eof, and capability answered by subclass overrides.
- cross-platform runtime manager (`bin/runtime.cmd`): fetch, list, use, and run Tcl runtimes — works from bash, powershell, or cmd.exe. `list -remote` compares local vs server runtimes with sha1 verification.
- Ability to create zipfs wrapped applications with all required libraries built in.
- Ability to create zipfs wrapped applications with all required libraries built in.
- Additional libraries
- Additional libraries
- improved fork of tcllib's imap4 (punk::imap4)
- improved fork of tcllib's imap4 (punk::imap4)
- netbox client library (punk::netbox)
- netbox client library (punk::netbox)
- telnet client with support for cp437
- telnet client with support for cp437
e.g can render mapscii.me with mouse support, and can view the ANSI max-headroom movie at 1984.ws
e.g can render mapscii.me with mouse support, and can view the ANSI max-headroom movie at 1984.ws
- A feature-rich argument processor that can be used purely to generate function documentation, or
- A feature-rich argument processor (punk::args) that can be used purely to generate function documentation, or
also to process and validate flags and values (punk::args)
also to process and validate flags and values (punk::args)
The argument processor/documentor can display command synopses, grids of applicable argument choices,
The argument processor/documentor can display command synopses, grids of applicable argument choices,
and indications of when short-forms (prefixes for flags/arguments/values) are applicable.
and indications of when short-forms (prefixes for flags/arguments/values) are applicable.
Commands documented with punk::args carry inline usage tables accessible via `i <command>` at the repl.
- In-shell help system: `i <command>` shows documented usage tables; `i help` lists registered help topics
(tcl, env, console, etc.) with per-topic documented usage.
#### missing
#### missing
- raw mode REPL (read-eval-print-loop) to allow commandline completion etc (undergoing development).
- raw mode REPL (read-eval-print-loop) to allow commandline completion etc (undergoing development).
- documentation is incomplete.
- documentation is incomplete, though the punk::args (PUNKARGS) system now provides inline usage tables and command documentation for many commands via `i <command>` at the repl.
- tests coverage is low.
- tests coverage is growing but not yet comprehensive — characterization suites exist for punk::args, punk::ns, punk::lib, punk::libunknown, punk::mix, shellthread, shellfilter, and console, among others.
- signal handling on unix-like platforms (ctrl-c implemented on windows only).
- signal handling on unix-like platforms (ctrl-c implemented on windows only).
#### very unripe parts:
#### very unripe parts:
- commandline options - in need of work to document and lock down specifics - in particular: punkshell somescript.tcl needs a fix to emit errors.
- shellfilter - api is clumsy
- shellfilter - api is clumsy
- scriptlib - will likely be reorganised/pruned significantly
- scriptlib - will likely be reorganised/pruned significantly
- theming
### Documentation
- `src/README.md` — detailed build instructions
- `CHANGELOG.md` — version history and recent changes
