kamfw

name	kamfw
description	Maintain MagicNet's shell KAM framework under src/MagicNet/lib/kamfw, including helpers, imports, i18n, logging, install filters, dependency checks, and EXIT handlers.

MagicNet KAM Framework

Use this skill only inside the MagicNet repository when changing src/MagicNet/lib/kamfw or callers that depend on it.

Inspect Before Editing

Search the framework and its callers before adding a helper:

rg '<symbol-or-behavior>' src/MagicNet/lib/kamfw src/MagicNet

Prefer an existing helper. Put a reusable helper in src/MagicNet/lib/kamfw/<name>.sh (or the established __name__.sh internal form) and load it through import; do not bury shared helpers in customize.sh or hooks.

Framework Contract

• Use the framework's print, info, warn, error, debug, and success wrappers for user-visible output. Use raw printf only for formatting that wrappers cannot express, and explain why.
• Register all user-visible text with set_i18n; retrieve it through i18n/t. List new or changed keys in the PR.
• Check optional commands with command -v. Missing required dependencies must fail fast through abort with an i18n message.
• Verify downloaded content with at least SHA-256; add signature verification when the trust model requires it. Never commit keys or secrets.
• Preserve user configuration by default. Interactive replacement needs explicit confirmation; non-interactive input uses the safe path (skip or create an update file).
• Do not rewrite system paths, start durable background processes, or silently downgrade behavior without explicit design and user-visible reporting.
• Keep functions small, single-purpose, and documented with rationale rather than narration.

TTY and Non-Interactive Behavior

There is no framework is_ci helper. Use the repository's existing TTY conventions instead of inventing one:

if [ -t 0 ] || [ -t 1 ]; then
    # interactive-capable path
else
    # safe non-interactive default
fi

Follow the owning helper when it uses stricter stdin-only checks such as [ -t 0 ].

Logging

logging.sh owns log behavior:

• KAM_LOGLEVEL / set_loglevel: ERROR, WARN, INFO, or DEBUG (default INFO)
• KAM_DEBUG=1: compatibility alias for debug logging
• KAM_LOGFILE: default $MODDIR/kam.log
• KAM_LOG_ROTATE_SIZE: accepts K/M/G suffixes

Use wrappers for level filtering and console output. Direct log remains a file-writing compatibility API.

EXIT Handlers

__at_exit__.sh exposes:

• at_exit_add, at_exit_remove, at_exit_list, at_exit_clear
• at_exit_register_trap, at_exit_unregister_trap
• __at_exit_install_from_filters

Current behavior is important:

• handlers run in registration order in the current shell via eval;
• one handler failure is logged and does not stop the remaining handlers;
• registration installs trap "__at_exit_master_handler" EXIT and does not preserve a pre-existing EXIT trap.

Do not describe handlers as subshell-isolated. Inspect compatibility before composing this helper with another EXIT trap.

Install Filters

Apply filters in this order:

1. install_exclude
2. install_include (may override an exclusion)
3. install_check preview
4. interactive confirmation where applicable
5. install

Both source-directory (KAM_MODULE_ROOT) and ZIP (ZIPFILE) flows are supported. Check unzip/zipinfo before ZIP operations and abort with an i18n message when absent.

Verification

For every change:

1. Exercise the changed helper through the same import path used in production.
2. Test both interactive and non-interactive branches.
3. Cover dependency-missing and failure paths.
4. For install filters, test directory and ZIP inputs plus include-overrides-exclude behavior.
5. For EXIT handlers, verify order, failure continuation, and interaction with existing traps.
6. Run the repository's relevant shell/static tests and record exact commands and results.

PR Checklist

Include:

• what changed and why;
• new/changed i18n keys;
• compatibility and security risks;
• interactive and non-interactive verification;
• dependency, network-integrity, logging, install, or EXIT-handler checks as applicable.