minishell/AGENTS.md

Repository Guidelines

Project Structure & Module Organization

• src/ holds the shell implementation, with submodules for builtins/, executor/, parser/, and variables/.
• src/builtins/ currently includes: cd, echo, env, exit, export, pwd, unset.
• include/ contains public headers used across modules.
• lib/ is populated at build time with third-party 42 libraries (libft, get_next_line, ft_printf, ft_args).
• docs/ stores project references and manual test notes (see docs/tests.md).
• build/ is the object output directory generated by make.

Build, Test, and Development Commands

• make or make all: build minishell (auto-clones required libs into lib/).
• make clean: remove objects in build/.
• make fclean: remove objects and the minishell binary (also cleans libs).
• make re: full rebuild.
• ./minishell: run locally after a build.
• make DEBUG=lldb or make DEBUG=valgrind or make DEBUG=address: rebuild with debug/ASan-friendly flags.

Coding Style & Naming Conventions

• The codebase follows 42 Norminette v4 rules. Run norminette *.c *.h (or on specific files) before submitting changes.
• Keep file names lowercase with underscores (e.g., src/builtins/echo/echo.c).
• Keep headers in include/ and expose only what modules need.
• Before adding or changing code, check allowed.txt to know which functions are permitted.
• Any function not listed in allowed.txt is not allowed in this project.

Parser & Lexer Functionality (Current src/parser)

• Runtime entrypoint is parse(line, minishell) from src/minishell.c (readline -> parse -> execute).
• parse splits the input line by unquoted | using extract_next_command + find_boundary.
• Each non-empty segment is trimmed and converted into a t_command via cmdnew.
• set_argv splits by unquoted spaces; quote characters are preserved in the resulting argument text.
• expand_envs is currently a TODO (no $VAR expansion is applied in parser stage).
• Redirections/heredoc are not converted into t_command.redirections yet in src/parser/parser.c.
• set_path resolves builtins and direct paths (/, ./, ../), otherwise searches PATH with access(..., F_OK).
• src/parser/lexer.c provides a separate lexer (lex) that tokenizes into TOKEN_WORD, TOKEN_PIPE, TOKEN_REDIRECT_IN, TOKEN_REDIRECT_OUT, TOKEN_APPEND, and TOKEN_HEREDOC.
• The lexer tracks single/double quote context so metacharacters inside quotes remain part of words.
• Meta runs are read as contiguous chunks in read_token (for example, repeated |/</> are captured as one token value).
• Current parser flow does not consume the lexer output yet.

Parser & Lexer Known Gaps

• src/parser/parser.c currently calls tokenize() with no valid declaration/definition in that unit, causing a build error with -Werror.
• src/parser/parser.c writes command->infile and command->outfile, but those fields are not present in t_command (include/core.h), causing build errors.
• src/parser/parser.c keeps a tokens variable that is unused, also failing under -Werror.
• include/parser.h exports parse only; lex is not declared in public headers.
• No explicit unmatched-quote syntax error handling is implemented in parser/lexer path.

Testing Guidelines

• There is no automated test runner. Use manual checks in docs/tests.md and basic shell behavior checks (pipes, redirects, builtins).
• A local builtin edge-case script exists at tests/builtins_edge_cases.sh (expects a compiled ./minishell).
• When debugging memory issues, run under valgrind and use the suppression file in valgrind/readline.supp.

Builtins Status

• cd: handles HOME fallback, cd - via OLDPWD, updates PWD/OLDPWD, and returns failure on invalid usage (too many arguments, missing HOME/OLDPWD).
• echo: supports repeated -n flags (-n, -nnn) and prints remaining args preserving spaces between tokens.
• env: prints current environment as KEY=VALUE; returns failure when called with extra arguments.
• exit: validates numeric argument (with overflow checks), returns 1 on too many arguments without exiting, and exits with 2 on non-numeric argument.
• export: supports NAME=VALUE and NAME (stored as empty value), validates identifiers, and returns failure when any identifier is invalid.
• pwd: prints working directory using dynamic getcwd and returns failure if getcwd fails.
• unset: validates identifiers and removes matching variables from the environment map.

Commit & Pull Request Guidelines

• Commit messages in this repo use a simple type: summary format (examples: update: ..., fix: ...). Keep summaries short and specific.
• For PRs, include:
  1. What changed and why.
  2. How to test (commands or manual steps).
  3. Notes on any parser/executor/builtin behavior changes.

Configuration Tips

• The project depends on readline; ensure your system has libreadline-dev or equivalent before building.