Module items 

Structs

ItemMeta

Lightweight item metadata available without authentication. Walks .joy/items/, peeks each file: if it is a JOYCRYPT blob, reads the zone name from the header without decrypting; if it is plaintext YAML, parses just enough to extract the id and crypt_zone fields. Used by joy crypt status / joy crypt ls / joy auth to count and locate Crypt content without prompting the user for a passphrase.

LockedItem

Lightweight placeholder for an encrypted item the caller cannot decrypt. ID is read from the filename, zone from the JOYCRYPT magic header; nothing is decrypted. Used by joy ls to render a [Crypted in zone <name>] row instead of failing the whole listing. See JOY-0174-D3.

Functions

delete_item

Delete an item by ID. Returns the deleted item.

detect_cycle

Check if adding a dependency would create a cycle. Returns the cycle path if one exists.

find_item_file

Find the file path for an item by its ID. Accepts both full IDs (JOY-0042-A3) and short-form (JOY-0042). Short-form returns an error if ambiguous (multiple matches).

list_item_metadata

Walk .joy/items/ and return one ItemMeta per item file. Never prompts, never decrypts. Use load_items when you need full Item objects.

load_item

Load a single item by ID.

load_items

Load all items from .joy/items/. Inaccessible-encrypted items are silently skipped (the caller treats them as not present). For surfacing locked-item placeholders, use load_items_with_locked.

load_items_with_locked

Load all items from .joy/items/, separating decryptable ones from encrypted blobs the caller has no zone-key for. Plaintext items and items whose zone key is currently active are returned as Item; items in zones without an active key are returned as LockedItem placeholders. See JOY-0174-D3.

next_id

Generate the next item ID by scanning existing files. Returns “ACRONYM-0001” for the first item, increments the highest found. All items share one number space regardless of type.

remove_references

Remove references to a deleted item from other items’ deps and parent fields.

save_item

Save an item to .joy/items/{ID}-{slug}.yaml.

title_hash_suffix

Generate 2 hex digits from the title for collision-safe IDs (ADR-027).

update_item

Update an item in place (overwrites its file).