# src/lib — Editable Tcl Library Source

## Purpose

Source of truth for all editable `pkgIndex.tcl`-based library packages. These are larger libraries that use the Tcl package index system rather than the `.tm` module format.

## Ownership

- Agents should edit implementation `.tcl` files in `src/lib/` subdirectories as the source of truth for library behaviour.
- `pkgIndex.tcl` files are loader maps — treat them as such unless the task is about package loading or registration.

## Local Contracts

- Treat `src/lib/` as the generic source tree; prefer it over `src/lib_tcl<major>/` unless version-specific.
- If a request starts from `pkgIndex.tcl`, resolve the mapped implementation file before analyzing or editing a proc.
- Libraries here include:
  - `app-punk/` — Punk REPL app entry (`app-punk::repl`)
  - `app-punkshell/` — Punkshell app entry (`app-punkshell`); on eof of its input channel the `env(PUNK_PIPE_EOF)` policy (`exit`|`interactive`|unset=console heuristic) decides between terminating and reopening the console for an interactive repl — automated callers should set `exit` or end piped input with an explicit `exit`
  - `app-punkscript/` — lean one-shot script runner behind the punk executable `script` subcommand (G-015): runs a file, a `lib:<name>` scriptlib script (resolved via `punk::path::scriptlib_resolve`; an extensionless call also matches an extensionless file whose first lines identify it as tcl - `# tcl` comment or tcl shebang incl. the sh-trampoline - with the called spelling winning when both spellings exist), or piped stdin in the default punk shell module/alias environment with honest exit codes; no shellfilter stacks or logging side effects, never falls into an interactive shell — the reliable path for automated/agent callers (prefer this over piping into `shell`); stdin form echoes the script's final result when non-empty; GUI parity with `tclsh` — a script leaving a registered Tk main loop is serviced until its window closes (so `script app.tcl` keeps a Tk app alive), while console scripts and errored scripts exit immediately
  - `app-shellspy/` — ShellSpy app entry (`app-shellspy`)
  - `app_shell/` — Shell app helpers (`app_shell`)
  - `app_shellrun/` — Shell run helpers (`app_shellrun`)
  - `app_project/` — Project app helpers (`app_project`)
  - `vfszip/` — VFS zip utilities

## Work Guidance

- Prefer generic or version-specific source trees over built, installed, VFS, or generated copies unless explicitly targeting those.
- After editing a library, run `tclsh src/make.tcl libs` to rebuild, then `tclsh src/make.tcl bakehouse` for a full rebuild from a clean checkout (the deprecated `project` alias still maps).
- New libraries should include a `pkgIndex.tcl` that correctly references the implementation file.

## Verification

- `tclsh src/make.tcl libs` completes without errors.
- `package require <libraryname>` resolves in the Punk shell after build.

## Child DOX Index

- `app-punk/` — Punk REPL app entry
- `app-punkshell/` — Punkshell app entry
- `app-punkscript/` — One-shot script runner (`script` subcommand)
- `app-shellspy/` — ShellSpy app entry
- `app_shell/` — Shell app helpers
- `app_shellrun/` — Shell run helpers
- `app_project/` — Project app helpers
- `vfszip/` — VFS zip utilities