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
- 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.
(renamed aliases and builtins and commands loaded from binaries will appear unmarked)
- `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.
- `d/` - list current directory (alias `./`)
also `d/ <globpattern>` to restrict output
- `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 `../`)
- `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.
- Additional libraries
- improved fork of tcllib's imap4 (punk::imap4)
- netbox client library (punk::netbox)
- 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
- 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)
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.
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
- raw mode REPL (read-eval-print-loop) to allow commandline completion etc (undergoing development).
- documentation is incomplete.
- tests coverage is low.
- 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 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).
#### 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
- scriptlib - will likely be reorganised/pruned significantly
- theming
### Documentation
- `src/README.md` — detailed build instructions
- `CHANGELOG.md` — version history and recent changes
