punkshell/src/lib/AGENTS.md

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