Handle State Library Skill

source "$(dirname "$0")/config/handle_state.sh"

init_function() {
  local temp_file="/tmp/resource"
  local resource_id="abc123"
  hs_persist_state_as_code "$@" -- temp_file resource_id
}

cleanup_function() {
  local temp_file resource_id
  hs_read_persisted_state "$@" -- temp_file resource_id
  rm -f "$temp_file"
  echo "Cleaned $resource_id"
  hs_destroy_state "$@" -- temp_file resource_id
}

local state=""
init_function -S state
cleanup_function -S state
init_function -S state

API Guidance

• Public library functions should expose -S directly instead of hiding it.
• Pass the full residual "$@" to hs_persist_state_as_code, hs_read_persisted_state, and hs_destroy_state.
• Put -- before the list of local variable names.
• The last -- is the effective separator; earlier ones may belong to the library's own API.
• If a library function consumes some of its own arguments first, forward the remaining parameter list unchanged and still use -- before the local names.

Reading State

• Prefer explicit restore lists: hs_read_persisted_state "$@" -- var1 var2.
• Avoid direct eval of the raw state object in new library code.
• hs_read_persisted_state can emit a locally generated probe snippet when no explicit variable list is provided, but this is best reserved for simple cases.
• An explicit -- with no following variable names suppresses probe-snippet output. This is useful when the list is generated by an expansion that can result in zero variables, and we want the function to stay silent on stdout.
• Missing requested variables are warnings, one per variable, unless -q is supplied.

Supported Variables

• Only local scalar variables (strings or numbers) are reliably preserved.
• Encode any other state variable as a string. See .github/skills/handle-state/references/templates.md.
• Re-declare the same locals in cleanup before calling hs_read_persisted_state.

Known Limitations (Tracked)

The following behaviors are tracked in GitHub; avoid them or apply workarounds.

• Unknown variable names are silently ignored (Issue #1).
• Function names are silently ignored (Issue #2).
• Indexed arrays only preserve the first element (Issue #3).
• Associative arrays are silently ignored (Issue #4).
• Namerefs are persisted as scalars; indirection is lost (Issue #5).

Workarounds

• Represent associative arrays as two encoded scalar strings.
• Represent indexed arrays as a single encoded scalar string.
• Convert other complex constructs into strings and rebuild them in cleanup.
• See .github/skills/handle-state/references/templates.md for examples.

Safety Notes

• hs_persist_state_as_code and hs_read_persisted_state still rely on eval internally; treat state objects as trusted input only.
• Avoid direct eval "$state" in new library code.
• Avoid name collisions when chaining state through a shared state variable; if libraries overlap variable names, prefer separate state variables or ensure cleanup destroys each library's own entries.
• Do not require stdout to carry state as part of a library API; reserve stdout for normal user-visible output.