Merge pull request #1 from DannyBen/refactor/argfile

Refactor as a single command and add `.shellkin` argfile support

Author: DannyBen

.github/workflows/test.yml

@@ -17,7 +17,7 @@ jobs:
     - name: Run Bats tests
       run: bats --recursive --print-output-on-failure test
     - name: Run Shellkin tests
-      run: ./shellkin test
+      run: ./shellkin
 
   ubuntu_setup:
     name: Setup on Ubuntu

AGENTS.md

@@ -4,21 +4,25 @@ Shellkin is a Bashly-based Gherkin-style test framework for shell scripts.
 
 ## Orientation
 
-- The project is organized by concern, not by command:
-  - `src/lib/syntax` parses and validates the language
-  - `src/lib/file` reads project files and orchestrates them
-  - `src/lib/runtime` contains framework execution internals
+- The project is organized by concept, not by command:
+  - `src/lib/feature` contains feature parsing and execution
+  - `src/lib/stepdef` contains step definition parsing and file loading
+  - `src/lib/step` contains step matching and execution
+  - `src/lib/support` contains support file loading
   - `src/lib/user_helpers` contains step-author-facing helpers
   - `src/lib/output` contains user-visible screen output
   - `src/lib/core` contains small shared primitives
-- Bashly command behavior lives in `src/commands`.
+- Bashly command behavior lives in `src/root_command.sh`.
 - Repo-level `features/` are used both for dogfooding and as examples.
 
 ## Conventions
 
 - Prefer small, focused functions.
 - Do not use nested function definitions; private helpers should still live at file scope.
+- Name private helpers with a `__` suffix on the namespace, such as `feature__helper`.
+- Place private helpers after the public functions in each file.
 - Use uppercase names for shared/framework state and lowercase for local variables.
+- Do not access CLI input such as `args[...]` anywhere under `src/lib`; normalize CLI input in the command layer and pass explicit parameters into lib functions.
 - Keep user-facing helper functions separate from framework internals.
 - Keep output logic isolated from parsing and runtime logic.
 - Prefer established Gherkin conventions and syntax over custom forms when practical.
@@ -27,6 +31,7 @@ Shellkin is a Bashly-based Gherkin-style test framework for shell scripts.
 
 - Prefer readable Bats tests over clever ones.
 - Use focused test files per function or per small public API surface.
+- Do not test private `__` helpers directly.
 - When file content is the subject of the test, prefer inline heredoc fixtures.
 - `write_file` in tests writes under `TEST_ROOT`.
 

README.md

@@ -14,7 +14,7 @@ Feature: --help
 
 Scenario: Run --help
   When I run 'shellkin --help'
-  Then the output should include 'shellkin COMMAND'
+  Then the output should include 'shellkin [TARGET] [OPTIONS]'
 ```
 
 and back them with shell step definitions:
@@ -36,8 +36,8 @@ Indenting the step body is recommended for readability, but optional.
 This setup script will download the latest shellkin release executable as well
 as the man pages.
 
-```shell
-$ curl -Ls get.dannyb.co/shellkin/setup | bash
+```bash
+curl -Ls get.dannyb.co/shellkin/setup | bash
 ```
 
 Feel free to inspect the [setup script](setup) before running.
@@ -63,7 +63,7 @@ through the repository `features/` directory.
 Implemented pieces include:
 
 - feature discovery from a directory or a single `.feature` file
-- optional support script loading from `support.sh`
+- optional support script loading with `--load`
 - step definition loading from `step_definitions/*.sh` and `*.bash`
 - step matching with `{token}` placeholders
 - `Background`, `Scenario`, `Given` / `When` / `Then`, `And` / `But`, and `*`
@@ -93,27 +93,50 @@ Implemented pieces include:
 
 ```bash
 # Run all repo features:
-shellkin test
+shellkin
 
 # Validate feature and step definition files without executing steps:
-shellkin validate
+shellkin --validate
 
 # Stop after the first failing scenario:
-shellkin test --fail-fast
+shellkin --fail-fast
 
 # Run a specific directory:
-shellkin test path/to/features
+shellkin path/to/features
 
 # Run a single feature file:
-shellkin test path/to/features/example.feature
+shellkin path/to/features/example.feature
 ```
 
 When a step fails, the remaining steps in that scenario are marked as skipped
 and are not executed.
 
-Use `shellkin validate` to check feature structure and step-definition matching
+Use `shellkin --validate` to check feature structure and step-definition matching
 without running any step bodies.
 
+## Configuration with `.shellkin`
+
+Shellkin supports configuration from a `.shellkin` argfile in the current
+working directory.
+
+This is useful for project-level defaults such as the default target,
+step-definitions directory, and support files:
+
+```text
+--default-target tests
+--stepdefs steps
+--load first_support.sh
+--load second_support.sh
+```
+
+The argfile format is intentionally simple:
+
+- Empty lines are ignored
+- Lines starting with `#` are ignored
+- Each other line becomes one argument
+- A flag and value can be written on one line or on two lines
+- Matching outer quotes are stripped
+
 ## AI Agent Skill
 
 This repository also provides a Codex skill for AI agents that need to write
@@ -145,26 +168,24 @@ Shellkin expects this structure:
 
 ```text
 features/
-├── support.sh
 ├── step_definitions/
 │   └── core.sh
 └── example.feature
 ```
 
 - Feature files live in the target directory.
-- If present, `support.sh` is sourced before step definitions are loaded.
 - Step definitions live in `step_definitions/` under that same directory.
-- Set `SHELLKIN_SUPPORT_FILE` to change the support script name relative to the
-  features directory.
+- Support files are loaded only when passed with `--load`.
+- `--stepdefs` and `--load` paths are relative to the features directory.
 
 ## Step Definitions
 
 Step definitions are shell snippets declared in files under
 `step_definitions/`.
 
-To share helper functions across step definition files, place them in
-`support.sh` in the features directory. Shellkin sources this file before it
-loads step definitions. You can rename it with `SHELLKIN_SUPPORT_FILE`.
+To share helper functions across step definition files, place them in a support
+script under the features directory and load it with `--load` or through
+`.shellkin`.
 
 ```bash
 @When I run '{command}'
@@ -270,7 +291,7 @@ and the [rush features](https://github.com/DannyBen/rush/tree/master/features).
 If you used the setup script, you can run this uninstall script:
 
 ```shell
-$ curl -Ls get.dannyb.co/shellkin/uninstall | bash
+curl -Ls get.dannyb.co/shellkin/uninstall | bash
 ```
 
 ## Contributing / Support

doc/shellkin-feature.5

@@ -133,8 +133,7 @@ Scenario: Create a file
   Then the file \(aqsomefile\(aq should exist
 .EE
 .SH SEE ALSO
-\f[B]shellkin\f[R](1), \f[B]shellkin\-test\f[R](1),
-\f[B]shellkin\-stepdefs\f[R](5)
+\f[B]shellkin\f[R](1), \f[B]shellkin\-stepdefs\f[R](5)
 .SH SOURCE CODE
 https://github.com/dannyben/shellkin
 .SH ISSUE TRACKER

doc/shellkin-feature.md

@@ -163,7 +163,7 @@ Scenario: Create a file
 SEE ALSO
 ==================================================
 
-**shellkin**(1), **shellkin-test**(1), **shellkin-stepdefs**(5)
+**shellkin**(1), **shellkin-stepdefs**(5)
 
 
 SOURCE CODE

doc/shellkin-stepdefs.5

@@ -145,8 +145,7 @@ temp_workspace() \f[B]{\f[R]
   \f[B][[\f[R] \-f \(dq$path\(dq \f[B]]]\f[R]
 .EE
 .SH SEE ALSO
-\f[B]shellkin\f[R](1), \f[B]shellkin\-test\f[R](1),
-\f[B]shellkin\-feature\f[R](5)
+\f[B]shellkin\f[R](1), \f[B]shellkin\-feature\f[R](5)
 .SH SOURCE CODE
 https://github.com/dannyben/shellkin
 .SH ISSUE TRACKER

doc/shellkin-stepdefs.md

@@ -170,7 +170,7 @@ temp_workspace() {
 SEE ALSO
 ==================================================
 
-**shellkin**(1), **shellkin-test**(1), **shellkin-feature**(5)
+**shellkin**(1), **shellkin-feature**(5)
 
 
 SOURCE CODE