Add custom modules with official/custom separation

[arifinsiddiqzisan]

🧠 Proposed Architecture (Official vs Custom Hard Separation)

1) New Custom Storage (Separate from Official Files)

Add new folders:

custom/modules/        # User-created module shell files
custom/docs/modules/   # User-created documentation (Markdown)
custom/index.tsv       # Metadata registry (module/command uniqueness + status)

Reason:
Official modules/*.sh remain untouched, ensuring that ak update / ak reload behavior stays stable.

---

2) Load Order in core/init.sh

1. Load official modules first:

   modules/*.sh
   

2. Then load custom modules:

   custom/modules/*.sh
   

3. Before sourcing custom commands, run a conflict guard:

   • If a custom command name already exists in the official command list:

     • Skip sourcing that custom command

     • Mark its status as:

       Already registered in official list
       

✅ This ensures that if a command later becomes official:

• Official command runs
• Custom version is automatically disabled until edited

---

3) Command Registry Utility (Single Source of Truth)

Create file:

core/registry.sh

Responsibilities

• Scan and index:

  • modules/*.sh (official)
  • custom/modules/*.sh (custom)

APIs

ak_module_exists <name>
ak_command_exists <name>

ak_is_official_module <name>
ak_is_official_command <name>

ak_reconcile_custom_conflicts

---

🧩 New CLI Commands

ak add

A short command to create custom modules.

Flow (fzf-based TUI)

1. Module name input + uniqueness check
2. Category / title input
3. Repeatedly add command pairs:

[ custom command ]  ->  [ genuine command ]

Also collect:

• description
• usage
• example

Output Files

custom/modules/<nn>_<module>.sh
custom/docs/modules/<nn>_<module>.md
custom/index.tsv

---

ak edit

Edit existing custom modules.

Features

• Show only custom modules (via fzf)

• Edit module metadata

• Manage commands:

  • Add
  • Edit
  • Delete

Constraints

• Cannot rename to an official module/command name
• Regenerates .sh and .md files automatically

---

ak custom

Displays:

• Custom modules

• Command status:

  active
  Already registered in official list
  

---

🖥 TUI UX Design (fzf-based)

The TUI is implemented as a single-form wizard interface inside the terminal using fzf.

Layout Overview

• Title:

  ak add - Single Form Wizard
  

• Navigation hint:

  Use ↑ ↓ to navigate, Enter to edit/select
  

• Status indicator:

  Commands queued: <count>
  

---

Form Fields

The interface presents a structured form:

Module Name     :
Category        :
Custom Command  :
Genuine Command :
Description     :
Usage           :
Example         :

• Each field is selectable via arrow keys
• Press Enter to edit the selected field
• Inputs are filled inline, one field at a time

---

Actions

At the bottom of the form:

[Save]
[Save & Add Another]
[Cancel]

Behavior

• Save

  • Saves the module with current data

• Save & Add Another

  • Saves current command pair
  • Resets command fields for adding another entry

• Cancel

  • Exits without saving

---

Interaction Model

• Fully keyboard-driven (no mouse required)
• No split UI — everything is handled in a single vertical form
• Clean and minimal UX optimized for terminal workflows

---

✅ Fully terminal-compatible
✅ No extra dependencies
✅ Structured form-based input (instead of prompt loops)
✅ Scalable for future fields/extensions

---

🧱 File Changes Plan

Create

core/registry.sh
core/add.sh
core/edit.sh

Update

core/init.sh

• Add routing for:

  add
  edit
  custom
  

• Load custom modules with conflict guard

---

Update

core/help.sh

• Include new commands in help output

• Show custom modules tagged as:

  [custom]
  

---

Create

custom/.gitkeep
custom/modules/.gitkeep
custom/docs/modules/.gitkeep

---

Documentation Updates

• README.md
• docs/src/MANUAL.md
• docs/src/contributing.md

---

🔒 Validation Rules

Module Name Validation

• Prefer lowercase slug:

  aws_tools
  mydev
  

• Reject if:

  • Exists in official modules

  • Exists in custom modules

  • Matches reserved keywords:

    help, update, reload, add, edit, ...
    

---

Command Name Validation

For each custom command:

• Reject if exists in official commands
• Reject if exists in custom commands (except itself during edit)
• Reject invalid shell identifiers

---

Edit Permissions

• ❌ Official modules: NOT editable/deletable
• ❌ Official commands: NOT editable/deletable
• ✅ Only custom modules and commands are mutable

---

🚀 Rollout Phases

Phase 1 (MVP)

• ak add wizard
• Save custom modules
• Load custom modules
• Uniqueness checks

---

Phase 2

• ak edit full CRUD
• Command-level edit/delete/add
• Metadata editing

---

Phase 3

• Conflict reconciliation after update/reload

• Auto-status:

  Already registered in official list
  

• Skip conflicting custom commands

---

Phase 4

• UI polish (better previews)
• Status listing improvements
• Documentation cleanup

---

✅ This architecture ensures:

• Full separation between official and custom
• Safe updates
• Future-proof command conflict handling
• Clean extensibility for users