punkshell/src/modules/punk/AGENTS.md

src/modules/punk — Core Punk Module Namespace

Purpose

Source of truth for all modules under the punk::* namespace. This is the primary development area for the Punk Shell project, containing the core shell, REPL, pipeline, ANSI, navigation, networking, and utility modules.

Ownership

• Agents should edit files here when modifying Punk module behaviour.
• Follow the module structure conventions from the parent src/modules/AGENTS.md strictly.
• Each subdirectory represents a sub-namespace (e.g., punk::ansi = ansi/, punk::mix = mix/).

Local Contracts

• Module filenames must use the literal suffix -999999.0a1.0.tm.
• Corresponding version files use <modulename>-buildversion.txt for the real version.
• The top-level punk-999999.0a1.0.tm is the main Punk module entry point.
• punk::lib (lib-999999.0a1.0.tm) provides core compatibility and utility functions.
• punk::args (args-999999.0a1.0.tm + args/) is the argument processing and documentation system.
• punk::repl (repl-999999.0a1.0.tm + repl/) is the interactive REPL engine.
• punk::mix (mix/) is the project/template/build system (mix CLI, commandset, templates).
• punk::cap (cap/ + cap-handlers/) is the capability/capture system.
• punk::nav (nav/) provides filesystem and namespace navigation (nav::fs, nav::ns).
• punk::ansi (ansi/) provides ANSI colour and terminal control.
• punk::net (net/) provides networking utilities (net::vxlan).
• punk::netbox (netbox/) provides the netbox client library (includes netbox::man).

Work Guidance

• New modules under punk::* should be created as <subpath>/<modulename>-999999.0a1.0.tm following the namespace-to-path convention.
• Use punk::args::parse with @id references in argdoc namespaces for public API procs.
• Private helpers go in namespace eval private { ... } blocks.
• Keep namespace export lists alphabetized.
• The #modpod-* folders contain files that get packed into .tm module archives during build — do not flatten them.
• Follow the parent src/modules/AGENTS.md "Versioning And Releases" rules: bump <modulename>-buildversion.txt on any API or behavior change and append a changelog comment line documenting the change.

Verification

• VS Code Tcl lint diagnostics are clean for modified .tm files when available.
• tclsh src/tests/modules/punk/<subpath>/tests/all.tcl passes for relevant tests.

Child DOX Index

• ansi/ — punk::ansi sub-namespace (colour, sauce, colourmap)
• args/ — punk::args sub-namespace (argument processing, moduledoc, testcmd)
• cap/ — punk::cap sub-namespace (capability handlers, templates)
• mix/ — punk::mix sub-namespace (CLI, commandset, templates for project/module building)
• nav/ — punk::nav sub-namespace (filesystem and namespace navigation)
• net/ — punk::net sub-namespace (networking utilities)
• netbox/ — punk::netbox sub-namespace (netbox client, man pages)
• repl/ — punk::repl sub-namespace (code thread management)