punkshell/.agents/skills/tcl-nslist/SKILL.md

name

description

tcl-nslist

Use BEFORE writing any new Tcl helper and BEFORE starting work in a punk namespace/package in this repo - to discover what already exists: what commands/procs a namespace exposes, or what an ensemble's implementation namespace contains. Run it first; reserve grep for full-text source-pattern searches - this lists the live interpreter, so it sees runtime-generated commands, aliases and imports grep cannot. Cost: one sub-1s side-effect-free punkshell invocation. Via punk::ns::get_ns_dicts (the machinery behind the interactive n// browser): child namespaces with loadable-package markers, commands classified by kind (proc/alias/ensemble/native/oo/imported), which commands have punk::args docs, optional whole-namespace usage synopses; auto-loads the package. No specific command name needed - for a named command's definition site/interface use the tcl-whatis skill.

tcl-nslist

Namespace/package discovery for the punkshell repo - the "what is available?" counterpart of tcl-whatis ("how do I call X?"). Asks the live interpreter via punk::ns::get_ns_dicts - the same machinery behind the interactive n// / n/// namespace browsers - so it reports what is actually loaded, including runtime-generated commands, aliases and imports that grep cannot see, and auto-loads the providing package when the namespace is not yet populated.

Command

Run from the repo root (punk91 lives in bin/, so bin/punk91 from the Bash tool; any punkshell kit works). Cost: sub-1s, no side effects.

punk91 src script lib:developer/nslist ?-synopsis? ?-pathcommands? <nsglob>...

lib:developer/nslist is punkshell script-path shorthand for scriptlib/developer/nslist.tcl.

• <nsglob> - namespace name or glob, qualified or not: punk::ns is listed as ::punk::ns::*. If the namespace does not exist, package require of the name (then of successively shorter :: prefixes) is attempted first. Last-segment glob chars filter members (punk::ns::ns*); glob chars in earlier segments match multiple namespaces (::tcl::*::d*); a trailing ::** segment recurses through all descendant namespaces (punk::nav::**). Quote glob arguments in PowerShell. An ensemble command name (e.g string) is followed to its implementation namespace, with a note.
• -synopsis - append punk::args usage lines for every documented command in the namespace (a one-call API cheat-sheet; large for big namespaces).
• -pathcommands - also list the commands resolvable via each namespace path entry.

Exit codes: 0 every pattern listed something, 1 some pattern matched nothing, 2 usage error.

Output fields

One block per matched namespace (blank-line separated); empty categories are omitted:

namespace:       ::punk::ns          fully-qualified namespace
children:        argdoc lib ...      child namespace tails
packagetails:    lib ...             children that are also loadable package names
packageprefixes: ...                 children with deeper loadable packages below them
commands:        147                 total member commands (count)
procs:           ...                 script procs
aliases:         ...                 interp aliases (may lack a same-named command)
ensembles:       ...
native:          ...                 C-implemented commands
imported:        ...                 imported from another namespace
other:           ...                 kinds not otherwise classified
exported:        ...                 commands matching the namespace export patterns
documented:      ...                 have punk::args docs - tcl-whatis gives full detail
exportpatterns:  {[a-z]*}            raw namespace export patterns
namespacepath:   ...                 extra namespaces this ns resolves commands from
note:            ...                 autoload / ensemble-follow / empty-namespace notes
synopsis:                            with -synopsis: usage line(s) per documented command

ooclasses/ooobjects/ooprivateclasses/ooprivateobjects/coroutines/interps/ zlibstreams lines appear when such commands exist. packagetails is the discovery lever: a child listed there can be package required and listed itself.

Caveats

• Keep the src launch argument: it loads and queries the working-tree modules under src/modules; without it the kit-stamped copies inside the executable answer instead.
• Load noise ("src mode: registered ...") goes to stderr; read stdout only (append 2>/dev/null in bash, 2>$null in PowerShell).
• Prefer the Bash tool over the PowerShell tool for these invocations: PowerShell-tool children get an attached console, which can flip punkshell's colour/terminal detection and change output classification.
• Only what is loaded in that session is reported. The script auto-requires the queried package, but a namespace can be populated further by other packages (e.g plugins) - an unexpectedly sparse listing may mean a related package is not loaded, not that the commands do not exist.
• documented: lists commands with registered punk::args definitions; undocumented commands are still real - tcl-whatis reports their proc signature and -body even without an argdoc.
• From Tcl code, the same data is available structurally: punk::ns::get_ns_dicts ::the::ns::* ?-allbelow <bool>? ?-nspathcommands <bool>? returns a list of dicts (keys documented - see punk91 src script lib:developer/whatis -doc punk::ns::get_ns_dicts), and punk::ns::nslist_dict accepts caller-relative globs. In an interactive punkshell the n// / n/// aliases render the same information.