`afad548`

Stabilize process API

Authored by

espadonne 3 weeks ago

SHA: afad5481c62901707dfcb2af70c314947a908c28
Parents: 02c19e3
Tree: ac4961c

8 changed files

Status	File	+	-
M	`.gitignore`	1	0
M	`README.md`	22	10
M	`docs/ROADMAP.md`	11	13
M	`src/fgof_process.f90`	87	33
A	`src/fgof_process_types.f90`	66	0
M	`test/test_command.f90`	2	1
A	`test/test_shell.f90`	14	0
A	`test/test_validation.f90`	33	0

.gitignoremodified

  build/
 +.docs/
  .DS_Store

README.mdmodified

  POSIX-first process and subprocess helpers for modern Fortran applications.
 -`fgof-process` is intended to be a small, standalone library that gives Fortran tools a more ergonomic process API than raw `execute_command_line` or ad hoc C interop.
 +`fgof-process` is intended to be a small, standalone library that gives Fortran tools a more ergonomic process API than raw `execute_command_line`, thin POSIX wrappers, or experimental process surfaces that still feel too low-level for real tooling.
 -Initial scope:
 +Current v1 target:
  - argv-first command construction
 -- synchronous process execution
 +- synchronous process execution on macOS and Linux
 +- explicit shell-command convenience through `/bin/sh -c`
  - environment overrides
  - working-directory overrides
 +- stdin support
  - stdout and stderr capture
  - exit-status reporting
  - timeout-aware execution
 +- structured, result-first errors
  Future scope:
  - async spawn and wait
  - signal helpers
  - PTY-friendly integration points for a future `fgof-pty`
 +- a dedicated `fgof-proc-test` companion package
  ## Status
 -Early scaffold.
 +Sprint 00 and 01 scaffold.
 -This repository is being created as the first package in the FortranGoingOnForty reusable library family and is intended to be consumed standalone or via the umbrella catalog repo at `lib-modules`.
 +This repository is the first package in the FortranGoingOnForty reusable library family and is intended to be consumed standalone or via the umbrella catalog repo at `lib-modules`.
  ## Package Goals
  - prefer argv-based execution over shell-string execution
  - make tests easy to write
  - stay useful for shells, editors, TUI apps, and developer tooling
 +- close a real ecosystem gap rather than mirroring `stdlib_system`
 -## Planned API Shape
 +## Public API Shape
  Primary module:
  - `fgof_process`
 -Initial public types:
 +Public types:
  - `process_command`
 -- `process_result`
  - `process_options`
 +- `process_result`
 -Initial public procedures:
 +Public procedures:
  - `command`
 +- `shell`
  - `run`
 +## Current Boundaries
++
 +- Direct POSIX backend is planned for v1.
 +- `stdlib_system` can inform behavior, but is not a required backend.
 +- Async process handles are explicitly deferred until after the sync-first release.
++
  ## Development Notes
  - POSIX first: macOS and Linux
  ## License
 -TBD
 +MIT

docs/ROADMAP.mdmodified

  ## v0.1
 -- establish standalone repo and `fpm` package
 -- define initial public types
 -- implement argv-first command construction
 -- implement synchronous `run`
 -- add basic tests
 +- establish the stable public API
 +- implement synchronous argv-first execution
 +- add shell convenience via explicit `shell()`
 +- support cwd, env, stdin, stdout, stderr, and timeouts
 +- ship a documented sync-first library that tool authors actually want to use
  ## v0.2
 -- stdout and stderr capture
 -- cwd and env overrides
 -- timeout handling
 -- richer errors
 +- async process handles
 +- richer process control
 +- signal helpers
 +- stronger process-fixture testing support
  ## v0.3
 -- async spawn or wait
 -- process handles
 -- kill and terminate helpers
 -- integration-test utilities
 +- companion packages such as `fgof-proc-test`
 +- possible PTY-facing integrations

src/fgof_process.f90modified

  module fgof_process
 +  use fgof_process_types, only : &
 +    FGOF_PROCESS_ERR_INVALID_COMMAND, &
 +    FGOF_PROCESS_ERR_INVALID_OPTION, &
 +    FGOF_PROCESS_ERR_NOT_IMPLEMENTED, &
 +    FGOF_PROCESS_MODE_ARGV, &
 +    FGOF_PROCESS_MODE_NONE, &
 +    FGOF_PROCESS_MODE_SHELL, &
 +    FGOF_PROCESS_OK, &
 +    process_command, &
 +    process_options, &
 +    process_result
    implicit none
    private
    public :: process_command
    public :: process_options
    public :: process_result
 +  public :: FGOF_PROCESS_MODE_NONE
 +  public :: FGOF_PROCESS_MODE_ARGV
 +  public :: FGOF_PROCESS_MODE_SHELL
 +  public :: FGOF_PROCESS_OK
 +  public :: FGOF_PROCESS_ERR_INVALID_COMMAND
 +  public :: FGOF_PROCESS_ERR_INVALID_OPTION
 +  public :: FGOF_PROCESS_ERR_NOT_IMPLEMENTED
    public :: command
 +  public :: shell
    public :: run
 -  type :: process_command
 -    character(len=:), allocatable :: program
 -    character(len=:), allocatable :: argv(:)
 -  end type process_command
+-
 -  type :: process_options
 -    character(len=:), allocatable :: cwd
 -    logical :: capture_stdout = .false.
 -    logical :: capture_stderr = .false.
 -    integer :: timeout_ms = 0
 -    character(len=:), allocatable :: env(:)
 -  end type process_options
+-
 -  type :: process_result
 -    integer :: exit_code = -1
 -    logical :: timed_out = .false.
 -    character(len=:), allocatable :: stdout
 -    character(len=:), allocatable :: stderr
 -    character(len=:), allocatable :: error_message
 -  end type process_result
+-
  contains
    function command(program, argv) result(cmd)
      character(len=*), intent(in) :: program
      character(len=*), intent(in), optional :: argv(:)
      type(process_command) :: cmd
 +    integer :: arg_len
      integer :: i
 +    cmd%mode = FGOF_PROCESS_MODE_ARGV
      cmd%program = trim(program)
      if (present(argv)) then
 -      allocate(character(len=len_trim(program)) :: cmd%argv(0))
 -      deallocate(cmd%argv)
 -      allocate(character(len=max(1, max_trimmed_length(argv))) :: cmd%argv(size(argv)))
 +      arg_len = max_trimmed_length(argv)
 +      allocate(character(len=arg_len) :: cmd%argv(size(argv)))
        do i = 1, size(argv)
          cmd%argv(i) = trim(argv(i))
        end do
      end if
    end function command
 +  function shell(command_line) result(cmd)
 +    character(len=*), intent(in) :: command_line
 +    type(process_command) :: cmd
++
 +    cmd%mode = FGOF_PROCESS_MODE_SHELL
 +    cmd%command_line = trim(command_line)
 +    allocate(character(len=1) :: cmd%argv(0))
 +  end function shell
++
    function run(cmd, options) result(res)
      type(process_command), intent(in) :: cmd
      type(process_options), intent(in), optional :: options
      type(process_result) :: res
 -    res%exit_code = -1
 -    res%timed_out = .false.
 -    res%stdout = ""
 -    res%stderr = ""
 -    res%error_message = "run() is not implemented yet"
 +    call init_result(res)
++
 +    select case (cmd%mode)
 +    case (FGOF_PROCESS_MODE_ARGV)
 +      if (.not. allocated(cmd%program)) then
 +        call set_error(res, FGOF_PROCESS_ERR_INVALID_COMMAND, "argv command program is not set")
 +        return
 +      end if
++
 +      if (len_trim(cmd%program) == 0) then
 +        call set_error(res, FGOF_PROCESS_ERR_INVALID_COMMAND, "argv command program must not be empty")
 +        return
 +      end if
++
 +    case (FGOF_PROCESS_MODE_SHELL)
 +      if (.not. allocated(cmd%command_line)) then
 +        call set_error(res, FGOF_PROCESS_ERR_INVALID_COMMAND, "shell command line is not set")
 +        return
 +      end if
++
 +      if (len_trim(cmd%command_line) == 0) then
 +        call set_error(res, FGOF_PROCESS_ERR_INVALID_COMMAND, "shell command line must not be empty")
 +        return
 +      end if
 -    if (.not. allocated(cmd%program)) then
 -      res%error_message = "command program is not set"
 +    case default
 +      call set_error(res, FGOF_PROCESS_ERR_INVALID_COMMAND, "command mode is not set")
        return
 -    end if
 +    end select
      if (present(options)) then
        if (options%timeout_ms < 0) then
 -        res%error_message = "timeout_ms must be >= 0"
 +        call set_error(res, FGOF_PROCESS_ERR_INVALID_OPTION, "timeout_ms must be >= 0")
          return
        end if
      end if
++
 +    call set_error(res, FGOF_PROCESS_ERR_NOT_IMPLEMENTED, "run() is not implemented yet")
    end function run
 +  subroutine init_result(res)
 +    type(process_result), intent(out) :: res
++
 +    res%launched = .false.
 +    res%completed = .false.
 +    res%timed_out = .false.
 +    res%exited_normally = .false.
 +    res%exit_code = -1
 +    res%term_signal = 0
 +    res%stdout = ""
 +    res%stderr = ""
 +    res%error_code = FGOF_PROCESS_OK
 +    res%error_message = ""
 +    res%elapsed_ms = 0
 +  end subroutine init_result
++
 +  subroutine set_error(res, code, message)
 +    type(process_result), intent(inout) :: res
 +    integer, intent(in) :: code
 +    character(len=*), intent(in) :: message
++
 +    res%error_code = code
 +    res%error_message = trim(message)
 +  end subroutine set_error
++
    integer function max_trimmed_length(values) result(max_len)
      character(len=*), intent(in) :: values(:)
      integer :: i

src/fgof_process_types.f90added

 +module fgof_process_types
 +  implicit none
 +  private
++
 +  public :: FGOF_PROCESS_MODE_NONE
 +  public :: FGOF_PROCESS_MODE_ARGV
 +  public :: FGOF_PROCESS_MODE_SHELL
 +  public :: FGOF_PROCESS_OK
 +  public :: FGOF_PROCESS_ERR_INVALID_COMMAND
 +  public :: FGOF_PROCESS_ERR_INVALID_OPTION
 +  public :: FGOF_PROCESS_ERR_SPAWN_FAILED
 +  public :: FGOF_PROCESS_ERR_EXEC_FAILED
 +  public :: FGOF_PROCESS_ERR_PIPE_FAILED
 +  public :: FGOF_PROCESS_ERR_TIMEOUT
 +  public :: FGOF_PROCESS_ERR_INTERNAL
 +  public :: FGOF_PROCESS_ERR_NOT_IMPLEMENTED
 +  public :: process_command
 +  public :: process_options
 +  public :: process_result
++
 +  integer, parameter :: FGOF_PROCESS_MODE_NONE = 0
 +  integer, parameter :: FGOF_PROCESS_MODE_ARGV = 1
 +  integer, parameter :: FGOF_PROCESS_MODE_SHELL = 2
++
 +  integer, parameter :: FGOF_PROCESS_OK = 0
 +  integer, parameter :: FGOF_PROCESS_ERR_INVALID_COMMAND = 10
 +  integer, parameter :: FGOF_PROCESS_ERR_INVALID_OPTION = 11
 +  integer, parameter :: FGOF_PROCESS_ERR_SPAWN_FAILED = 20
 +  integer, parameter :: FGOF_PROCESS_ERR_EXEC_FAILED = 21
 +  integer, parameter :: FGOF_PROCESS_ERR_PIPE_FAILED = 22
 +  integer, parameter :: FGOF_PROCESS_ERR_TIMEOUT = 23
 +  integer, parameter :: FGOF_PROCESS_ERR_INTERNAL = 99
 +  integer, parameter :: FGOF_PROCESS_ERR_NOT_IMPLEMENTED = 1000
++
 +  type :: process_command
 +    integer :: mode = FGOF_PROCESS_MODE_NONE
 +    character(len=:), allocatable :: program
 +    character(len=:), allocatable :: argv(:)
 +    character(len=:), allocatable :: command_line
 +  end type process_command
++
 +  type :: process_options
 +    character(len=:), allocatable :: cwd
 +    character(len=:), allocatable :: stdin
 +    logical :: capture_stdout = .false.
 +    logical :: capture_stderr = .false.
 +    integer :: timeout_ms = 0
 +    character(len=:), allocatable :: env_set(:)
 +    character(len=:), allocatable :: env_unset(:)
 +  end type process_options
++
 +  type :: process_result
 +    logical :: launched = .false.
 +    logical :: completed = .false.
 +    logical :: timed_out = .false.
 +    logical :: exited_normally = .false.
 +    integer :: exit_code = -1
 +    integer :: term_signal = 0
 +    character(len=:), allocatable :: stdout
 +    character(len=:), allocatable :: stderr
 +    integer :: error_code = FGOF_PROCESS_OK
 +    character(len=:), allocatable :: error_message
 +    integer :: elapsed_ms = 0
 +  end type process_result
++
 +end module fgof_process_types

test/test_command.f90modified

  program test_command
 -  use fgof_process, only : process_command, command
 +  use fgof_process, only : FGOF_PROCESS_MODE_ARGV, command, process_command
    implicit none
    type(process_command) :: cmd
    cmd = command("printf", ["hello", "world"])
 +  if (cmd%mode /= FGOF_PROCESS_MODE_ARGV) error stop "mode mismatch"
    if (.not. allocated(cmd%program)) error stop "program not allocated"
    if (cmd%program /= "printf") error stop "program mismatch"
    if (.not. allocated(cmd%argv)) error stop "argv not allocated"

test/test_shell.f90added

 +program test_shell
 +  use fgof_process, only : FGOF_PROCESS_MODE_SHELL, process_command, shell
 +  implicit none
++
 +  type(process_command) :: cmd
++
 +  cmd = shell("printf 'hello from shell'")
++
 +  if (cmd%mode /= FGOF_PROCESS_MODE_SHELL) error stop "mode mismatch"
 +  if (.not. allocated(cmd%command_line)) error stop "command_line not allocated"
 +  if (cmd%command_line /= "printf 'hello from shell'") error stop "command_line mismatch"
 +  if (.not. allocated(cmd%argv)) error stop "argv not allocated"
 +  if (size(cmd%argv) /= 0) error stop "shell argv should be empty"
 +end program test_shell

test/test_validation.f90added

 +program test_validation
 +  use fgof_process, only : &
 +    FGOF_PROCESS_ERR_INVALID_COMMAND, &
 +    FGOF_PROCESS_ERR_INVALID_OPTION, &
 +    FGOF_PROCESS_MODE_ARGV, &
 +    process_command, &
 +    process_options, &
 +    process_result, &
 +    run, &
 +    shell
 +  implicit none
++
 +  type(process_command) :: argv_cmd
 +  type(process_command) :: shell_cmd
 +  type(process_options) :: opts
 +  type(process_result) :: res
++
 +  argv_cmd%mode = FGOF_PROCESS_MODE_ARGV
 +  argv_cmd%program = ""
 +  allocate(character(len=1) :: argv_cmd%argv(0))
++
 +  res = run(argv_cmd)
 +  if (res%error_code /= FGOF_PROCESS_ERR_INVALID_COMMAND) error stop "empty argv command should be invalid"
++
 +  shell_cmd = shell("")
 +  res = run(shell_cmd)
 +  if (res%error_code /= FGOF_PROCESS_ERR_INVALID_COMMAND) error stop "empty shell command should be invalid"
++
 +  shell_cmd = shell("printf 'ok'")
 +  opts%timeout_ms = -1
 +  res = run(shell_cmd, opts)
 +  if (res%error_code /= FGOF_PROCESS_ERR_INVALID_OPTION) error stop "negative timeout should be invalid"
 +end program test_validation