bootstrap.bash File Reference

Provides the bootstrap engine source entry point. More...

Functions
int	bootstrap_print_help ()
	Prints the currently supported command-line usage summary.
int	bootstrap_print_usage_error (String message)
	Prints a human-readable command-line usage error.
int	bootstrap_parse_arguments (String arguments)
	Parses supported long-form command-line options.
int	bootstrap_run_placeholder ()
	Runs the placeholder operation when no manifest was supplied.
int	bootstrap_print_action_record (String action, String package, String operator, String version)
	Prints one human-readable dry-run line for an Action Record.
int	bootstrap_print_action_explanation (String action, String package, String operator, String version, String source, String line_number)
	Prints provenance and architectural context for one Action Record.
int	bootstrap_print_resolved_action (String action, String manager, String package, String operator, String version)
	Prints one human-readable dry-run line for a Resolved Action.
int	bootstrap_print_resolved_action_explanation (String action, String manager, String package, String operator, String version, String source, String line_number)
	Prints explanatory context for one Resolved Action.
int	bootstrap_print_manifest_scope (String heading)
	Prints the ordered manifests included in the current invocation.
int	bootstrap_print_dry_run_plan (String action_file, String resolved_file)
	Renders a planned and resolved dry-run action list for all manifests.
int	bootstrap_preflight_manifests (String action_file, String resolved_file)
	Parses, plans, and resolves every supplied manifest before execution.
int	bootstrap_run_dry_run_plan ()
	Preflights all manifests and prints one read-only invocation plan.
int	bootstrap_print_execution_result (String status, String exit_code, String action, String manager, String package, String message)
	Prints one human-readable execution result line.
int	bootstrap_print_execution_results (String result_file)
	Prints a human-readable execution summary from Execution Result records.
int	bootstrap_run_execution_plan ()
	Preflights all manifests before executing the complete resolved plan.
int	main (String arguments)
	Runs the bootstrap command-line entry point.

Detailed Description

Provides the bootstrap engine source entry point.

This file contains the public command-line entry point that is assembled into dist/bootstrap.bash. The entry point owns user-facing option handling, dry-run rendering, execution-result rendering, and the final choice between planning and execution.

The command model is intentionally a single primary operation modified by explicit long options. That keeps the bootstrap experience compact while still making user intent visible through flags such as –dry-run, –explain, –verbose, and –quiet.

This source file is assembled into the distribution artifact together with the runtime, manifest, planner, resolver, backend, and executor modules. It should therefore avoid duplicating lower-level package-manager policy.

Examples

bootstrap.bash --help
bootstrap.bash --dry-run --explain packages.txt
bootstrap.bash --package-manager apt packages.txt

Function Documentation

bootstrap_parse_arguments()

int bootstrap_parse_arguments

(

String

arguments

)

Parses supported long-form command-line options.

The parser intentionally accepts only explicit long options. Short aliases are not added yet because the ADRs prefer clarity and compatibility over a broad convenience surface.

The parser records option state in runtime context for later phases. Manifest planning and execution happen after parsing so argument validation remains separate from pipeline orchestration.

Parameters

arguments

Command-line arguments supplied by the user.

Return values

0	All arguments were parsed successfully.
64	The user supplied unsupported, unexpected, or contradictory input.

Examples

bootstrap_parse_arguments --dry-run --package-manager apt packages.txt
bootstrap_parse_arguments --verbose packages.txt

bootstrap_preflight_manifests()

int bootstrap_preflight_manifests	(	String	action_file,
		String	resolved_file
	)

Parses, plans, and resolves every supplied manifest before execution.

Each manifest is planned into a private temporary file first. Its Action Records are appended to the invocation plan only after that manifest succeeds, preventing partial records from a failed manifest from entering the executable plan. Resolution runs only after every manifest has parsed and planned successfully. This establishes the ADR-049 global preflight barrier.

Parameters

action_file	Destination for the complete ordered Action Record stream.
resolved_file	Destination for the complete ordered Resolved Action stream.

Return values

0	Every manifest parsed, planned, and resolved successfully.
65	A manifest could not be read, parsed, or planned.
69	At least one planned action could not be resolved.

bootstrap_print_action_explanation()

int bootstrap_print_action_explanation	(	String	action,
		String	package,
		String	operator,
		String	version,
		String	source,
		String	line_number
	)

Prints provenance and architectural context for one Action Record.

Explain output should make the plan easier to inspect without pretending that executor work has already happened. This helper reports the manifest line that produced the action and restates the planner boundary.

Parameters

action	Action Record type.
package	Package name associated with the action.
operator	Optional version constraint operator.
version	Optional version constraint value.
source	Manifest source path preserved by the parser and planner.
line_number	Manifest line number preserved by the parser and planner.

Return values

0	The explanation was printed successfully.
65	The Action Record type was unsupported by this renderer.

Examples

bootstrap_print_action_explanation install-package shellcheck "" "" packages.txt 3
bootstrap_print_action_explanation install-package bash ">=" 5.0 packages.txt 4

bootstrap_print_action_record()

int bootstrap_print_action_record	(	String	action,
		String	package,
		String	operator,
		String	version
	)

Prints one human-readable dry-run line for an Action Record.

The planner emits abstract Action Records. This function renders the current install-package action model without resolving package managers or command lines. Unknown action types are reported as manifest errors.

Parameters

action	Action Record type.
package	Package name associated with the action.
operator	Optional version constraint operator.
version	Optional version constraint value.

Return values

0	The Action Record was rendered successfully.
65	The Action Record type was unsupported by this renderer.

Examples

bootstrap_print_action_record install-package shellcheck
bootstrap_print_action_record install-package bash ">=" 5.0

bootstrap_print_dry_run_plan()

int bootstrap_print_dry_run_plan	(	String	action_file,
		String	resolved_file
	)

Renders a planned and resolved dry-run action list for all manifests.

Dry-run output is deliberately generated from Action Records and Resolved Actions rather than parser records. This keeps user-facing output aligned with the same pipeline that later executor phases consume while guaranteeing that dry-run mode performs no system changes.

Parameters

action_file	File containing pipe-delimited Action Records.
resolved_file	File containing pipe-delimited Resolved Actions.

Standard Output

Human-readable dry-run output.

Return values

0	The dry-run plan was printed successfully.
65	An Action Record could not be rendered.
69	A Resolved Action could not be rendered.

Examples

bootstrap_print_dry_run_plan /tmp/bootstrap-plan.txt /tmp/bootstrap-resolved.txt

bootstrap_print_execution_result()

int bootstrap_print_execution_result	(	String	status,
		String	exit_code,
		String	action,
		String	manager,
		String	package,
		String	message
	)

Prints one human-readable execution result line.

Execution Results are the final records in the pipeline. This renderer keeps user-facing reporting separate from executor behavior so executor tests can focus on record contracts.

Parameters

status	Execution Result status such as success, already-satisfied, or failed.
exit_code	Process-style exit code attached to the result.
action	Resolved Action type that was executed.
manager	Backend or package manager that handled the action.
package	Package name associated with the result.
message	Human-readable execution result message.

Standard Output

Human-readable execution output.

Return values

0	The Execution Result was printed successfully.

Examples

bootstrap_print_execution_result success 0 install-package apt shellcheck installed
bootstrap_print_execution_result already-satisfied 0 install-package apt bash "already installed"

bootstrap_print_execution_results()

int bootstrap_print_execution_results

(

String

result_file

)

Prints a human-readable execution summary from Execution Result records.

This helper renders the structured records emitted by the executor. It keeps output formatting outside the executor so executor tests can focus on record contracts while CLI tests focus on user-visible behavior.

Parameters

result_file

File containing pipe-delimited Execution Result records.

Standard Output

Human-readable execution output.

Return values

0	Execution Results were printed successfully.

Examples

bootstrap_print_execution_results /tmp/bootstrap-results.txt

bootstrap_print_help()

int bootstrap_print_help

(

)

Prints the currently supported command-line usage summary.

The help output documents behavior that is implemented and tested. Operational options are listed because the parser recognizes them and records their state before planning or execution begins.

Standard Output

Help text.

Return values

0	Help text was printed successfully.

Examples

bootstrap_print_help

bootstrap_print_manifest_scope()

int bootstrap_print_manifest_scope

(

String

heading

)

Prints the ordered manifests included in the current invocation.

Single-manifest output retains the established wording for compatibility. Multi-manifest output lists every path explicitly so users can verify the preflight scope and correlate later provenance-bearing diagnostics.

Parameters

heading

Singular heading prefix used before the manifest description.

Return values

0	The manifest scope was printed successfully.

bootstrap_print_resolved_action()

int bootstrap_print_resolved_action	(	String	action,
		String	manager,
		String	package,
		String	operator,
		String	version
	)

Prints one human-readable dry-run line for a Resolved Action.

Resolved Actions bind abstract planner output to the current platform without executing anything. This renderer names the selected package manager while avoiding command-line syntax that could be mistaken for completed work.

Parameters

action	Resolved Action type.
manager	Package manager selected by the resolver.
package	Package name associated with the action.
operator	Optional version constraint operator.
version	Optional version constraint value.

Return values

0	The Resolved Action was rendered successfully.
69	The Resolved Action type was unsupported by this renderer.

Examples

bootstrap_print_resolved_action install-package apt shellcheck
bootstrap_print_resolved_action install-package apt bash ">=" 5.0

bootstrap_print_resolved_action_explanation()

int bootstrap_print_resolved_action_explanation	(	String	action,
		String	manager,
		String	package,
		String	operator,
		String	version,
		String	source,
		String	line_number
	)

Prints explanatory context for one Resolved Action.

This helper describes how the current environment resolved a planned action. It is deliberately phrased as future intent rather than completed work because dry-run mode must never mutate the system.

Parameters

action	Resolved Action type.
manager	Package manager selected by the resolver.
package	Package name associated with the resolved action.
operator	Optional version constraint operator.
version	Optional version constraint value.
source	Manifest source path preserved for provenance.
line_number	Manifest line number preserved for provenance.

Return values

0	The explanation was printed successfully.
69	The Resolved Action type was unsupported by this renderer.

Examples

bootstrap_print_resolved_action_explanation install-package apt shellcheck "" "" packages.txt 3
bootstrap_print_resolved_action_explanation install-package apt bash ">=" 5.0 packages.txt 4

bootstrap_print_usage_error()

int bootstrap_print_usage_error

(

String

message

)

Prints a human-readable command-line usage error.

Unsupported or contradictory options fail conservatively instead of being ignored. This keeps misspelled flags visible and avoids implying that the engine accepted an instruction that it cannot safely honor.

Parameters

message

The specific usage problem to show to the user.

Standard Error

Diagnostic text.

Return values

0	The diagnostic was printed successfully.

Examples

bootstrap_print_usage_error "unsupported option: --force"

bootstrap_run_dry_run_plan()

int bootstrap_run_dry_run_plan

(

)

Preflights all manifests and prints one read-only invocation plan.

Dry-run uses the same complete Action Record and Resolved Action streams that execution would consume. No output plan is rendered until every manifest has crossed the global preflight barrier successfully.

Return values

0	All manifests were preflighted and displayed successfully.
65	A manifest could not be parsed or planned.
69	The complete action set could not be resolved on this system.

bootstrap_run_execution_plan()

int bootstrap_run_execution_plan

(

)

Preflights all manifests before executing the complete resolved plan.

No executor is invoked until every supplied manifest has parsed, planned, and resolved successfully. The resulting Resolved Action stream preserves manifest argument order and source provenance, satisfying ADR-049 without concatenating source files or losing filename and line-number diagnostics.

Return values

0	The complete manifest set executed successfully or required no work.
65	At least one manifest could not be parsed or planned.
69	At least one planned action could not be resolved.
70	At least one resolved action failed during execution.

bootstrap_run_placeholder()

int bootstrap_run_placeholder

(

)

Runs the placeholder operation when no manifest was supplied.

This function preserves the established no-manifest behavior while respecting –quiet as the only flag whose behavior is meaningful without manifest input.

Standard Output

A placeholder status message unless quiet mode is enabled.

Return values

0	The placeholder operation completed successfully.

Examples

bootstrap_run_placeholder

main()

int main

(

String

arguments

)

Runs the bootstrap command-line entry point.

Discovery commands such as –help and –version return immediately and must be used by themselves. Operational flags are parsed, configuration is validated, and a supplied manifest is then either dry-run planned or executed.

Parameters

arguments

Command-line arguments supplied by the user.

Output Streams

Command output on standard output, or diagnostics on standard error.

Return values

0	The command completed successfully.
64	The user supplied unsupported or invalid command-line arguments.
65	Manifest parsing or planning failed.
69	Resolution failed for the current system.
70	Execution failed for at least one resolved action.

Examples

main --help
main --dry-run --explain packages.txt
main --package-manager apt packages.txt