Built-in Actions¶
All built-in actions are re-exported from finecode_extension_api.actions. Use the short form finecode_extension_api.actions.<ClassName> as the source when declaring actions in pyproject.toml or preset.toml.
lint¶
Run linting on a source artifact or specific files.
- Source:
finecode_extension_api.actions.LintAction - Default handler execution: concurrent
Payload fields:
| Field | Type | Default | Description |
|---|---|---|---|
target |
"project" | "files" |
"project" |
Lint the whole source artifact (target="project") or specific files |
file_paths |
list[Path] |
[] |
Files to lint (required when target="files") |
Result: list of diagnostics (file, line, column, message, severity)
lint_files¶
Lint a specific set of files. Internal action dispatched by lint.
- Source:
finecode_extension_api.actions.LintFilesAction - Default handler execution: concurrent
The built-in LintFilesDispatchHandler groups the given files by language and dispatches one call per language to the matching language subaction — any action declaring PARENT_ACTION = LintFilesAction and the corresponding LANGUAGE. Files of unknown language are skipped.
lint_python_files¶
Lint Python source files and report diagnostics. Language-specific subaction of lint_files.
- Source:
finecode_extension_api.actions.LintPythonFilesAction - Default handler execution: concurrent
Payload fields: same as lint_files.
Register Python linting tools (ruff, mypy, …) as handlers for this action.
format¶
Format a source artifact or specific files.
- Source:
finecode_extension_api.actions.FormatAction - Default handler execution: sequential
Payload fields:
| Field | Type | Default | Description |
|---|---|---|---|
save |
bool |
true |
Write formatted content back to disk |
target |
"project" | "files" |
"project" |
Format the whole source artifact (target="project") or specific files |
file_paths |
list[Path] |
[] |
Files to format (required when target="files") |
Note
The save payload field controls whether changes are written to disk. The built-in SaveFormatFileHandler reads this flag. If you omit the save handler from your preset, files won't be written regardless.
format_files¶
Format a specific set of files. Internal action dispatched by format.
- Source:
finecode_extension_api.actions.FormatFilesAction - Default handler execution: sequential
The built-in FormatFilesIterateHandler iterates over all files and delegates each to format_file. Language routing is handled by format_file via its dispatch handler — format_files has no language awareness.
format_file¶
Format a single file. Item-level action; handlers run sequentially as a pipeline.
- Source:
finecode_extension_api.actions.FormatFileAction - Default handler execution: sequential
Payload fields:
| Field | Type | Description |
|---|---|---|
file_path |
ResourceUri |
The single file to format |
save |
bool |
Whether to write the result back to disk |
Run context kwargs (FormatFileCallerRunContextKwargs):
| Field | Type | Default | Description |
|---|---|---|---|
file_editor_session |
IFileEditorSession \| None |
None |
Shared session from a parent action. If absent, the context opens its own. |
file_info |
FileInfo \| None |
None |
Pre-read file content. If absent, the context reads the file itself (with block=True). |
When called standalone (e.g. IDE on-save), no kwargs are needed — the context creates its own session and reads the file. When called from format_files, the iterate handler passes the parent session. When called from the dispatch handler into a language subaction, both session and file info are passed to avoid redundant reads.
Result fields:
| Field | Type | Description |
|---|---|---|
changed |
bool |
Whether the file content was modified |
code |
str |
The formatted content |
Handlers read and update run_context.file_info to pass formatted content to the next handler in the pipeline.
format_python_file¶
Format a single Python file. Language-specific item-level subaction of format_file.
- Source:
finecode_extension_api.actions.FormatPythonFileAction - Default handler execution: sequential
Payload fields: same as format_file.
Register Python formatting tools (ruff, isort, …) as handlers for this action. Handler order matters — they run sequentially as a pipeline.
precommit¶
Run configured code quality checks on git-staged files before commit. This action is not registered by default; add it through the fine_precommit preset or declare tool.finecode.action.precommit yourself.
- Source:
finecode_extension_api.actions.PrecommitAction - Default handler execution: sequential
Payload fields:
| Field | Type | Default | Description |
|---|---|---|---|
file_paths |
list[Path] |
[] |
Explicit file list. Empty means auto-detect staged files from git (done by StagedFilesDiscoveryHandler). |
Result fields:
| Field | Type | Description |
|---|---|---|
action_results |
dict[str, RunActionResult] |
Results keyed by action name (for example, "lint"). The overall return_code is ERROR if any sub-result is an error. |
Run context (PrecommitRunContext):
| Field | Type | Description |
|---|---|---|
staged_files |
list[Path] \| None |
Populated by StagedFilesDiscoveryHandler. None = discovery has not run (bridge handlers raise); [] = no staged files (bridge handlers skip). |
Handler roles:
StagedFilesDiscoveryHandler— must be first; detects staged files viagit diff --cached --name-only --diff-filter=ACMRand writes torun_context.staged_files.- Bridge handlers (for example,
LintPrecommitBridgeHandler) — each delegates to one existing action passing staged files. Register additional bridge handlers to run more tools.
See Using Git Hooks for setup instructions.
list_tests¶
Discover tests and return their hierarchical structure without running them.
- Source:
finecode_extension_api.actions.ListTestsAction
Payload fields:
| Field | Type | Default | Description |
|---|---|---|---|
file_paths |
list[Path] |
[] |
Files or directories to search. Empty means the handler uses its own defaults (e.g. testpaths in pytest.ini). |
Result fields:
| Field | Type | Description |
|---|---|---|
tests |
list[TestItem] |
Tree of discovered tests. Each node carries a test_id usable in run_tests. |
run_tests¶
Execute tests and return structured pass/fail results.
- Source:
finecode_extension_api.actions.RunTestsAction
Payload fields:
| Field | Type | Default | Description |
|---|---|---|---|
file_paths |
list[Path] |
[] |
Test files or directories to run. Empty means handler defaults. |
test_ids |
list[TestId] |
[] |
Specific tests to run, obtained from list_tests. |
markers |
list[str] |
[] |
Marker/tag names to filter (e.g. ["unit", "slow"]). Handlers map these to runner-specific flags. |
Result fields:
| Field | Type | Description |
|---|---|---|
test_results |
list[TestCaseResult] |
One entry per executed test with outcome, duration, and failure message. |
build_artifact¶
Build a distributable artifact (e.g. a Python wheel).
- Source:
finecode_extension_api.actions.BuildArtifactAction
Payload fields:
| Field | Type | Default | Description |
|---|---|---|---|
src_artifact_def_path |
Path \| None |
None |
Path to the artifact definition. If omitted, builds the current source artifact. |
Result fields:
| Field | Type | Description |
|---|---|---|
src_artifact_def_path |
Path |
Path of the artifact that was built |
build_output_paths |
list[Path] |
Paths of the generated build outputs |
get_src_artifact_version¶
Get the current version of a source artifact.
- Source:
finecode_extension_api.actions.GetSrcArtifactVersionAction
Default handler in this repo: fine_python_setuptools_scm.GetSrcArtifactVersionSetuptoolsScmHandler
get_dist_artifact_version¶
Get the version of a distributable artifact.
- Source:
finecode_extension_api.actions.GetDistArtifactVersionAction
get_src_artifact_language¶
Get the primary programming language of a source artifact. Used by language-aware dispatch handlers (e.g. lock_dependencies) to route to the appropriate language-specific subaction.
- Source:
finecode_extension_api.actions.GetSrcArtifactLanguageAction
Payload fields:
| Field | Type | Description |
|---|---|---|
src_artifact_def_path |
Path |
Path to the artifact definition file |
Result fields:
| Field | Type | Description |
|---|---|---|
language |
str |
Language identifier, e.g. "python", "javascript", "rust" |
get_src_artifact_registries¶
List available registries for publishing an artifact.
- Source:
finecode_extension_api.actions.GetSrcArtifactRegistriesAction
lock_dependencies¶
Lock the dependencies of a source artifact.
- Source:
finecode_extension_api.actions.LockDependenciesAction
Payload fields:
| Field | Type | Description |
|---|---|---|
src_artifact_def_path |
Path |
Path to the artifact definition file (e.g. pyproject.toml, package.json) |
output_dir |
Path |
Directory where lock files will be written. The handler decides filenames. |
Result fields:
| Field | Type | Description |
|---|---|---|
lock_file_paths |
list[Path] |
All lock files generated — one entry for single-lock, N entries for multi-lock |
| --- |
lock_python_dependencies¶
Lock Python dependencies for a specific Python version and platform. Language-specific subaction of lock_dependencies.
- Source:
finecode_extension_api.actions.LockPythonDependenciesAction
Payload fields:
| Field | Type | Default | Description |
|---|---|---|---|
src_artifact_def_path |
Path |
Path to the artifact definition file (e.g. pyproject.toml) |
|
output_dir |
Path |
Directory where lock files will be written | |
target_python_version |
str \| None |
None |
Python version to target, e.g. "3.11". Defaults to the running interpreter. |
target_platform |
str \| None |
None |
Wheel platform tag to target, e.g. "linux_x86_64". Defaults to the current platform. |
Result fields: same as lock_dependencies.
target_python_version and target_platform are typically used for target projection or target-specific lock generation.
See Designing Actions for the rationale behind generic vs. language-specific actions.
publish_artifact¶
Publish a built artifact.
- Source:
finecode_extension_api.actions.PublishArtifactAction
publish_artifact_to_registry¶
Publish an artifact to a specific registry.
- Source:
finecode_extension_api.actions.PublishArtifactToRegistryAction
is_artifact_published_to_registry¶
Check whether a specific version of an artifact is already published.
- Source:
finecode_extension_api.actions.IsArtifactPublishedToRegistryAction
verify_artifact_published_to_registry¶
Verify that publishing succeeded by checking the registry.
- Source:
finecode_extension_api.actions.VerifyArtifactPublishedToRegistryAction
list_src_artifact_files_by_lang¶
List source files grouped by programming language.
- Source:
finecode_extension_api.actions.ListSrcArtifactFilesByLangAction
group_src_artifact_files_by_lang¶
Group source files by language (internal, used by language-aware actions).
- Source:
finecode_extension_api.actions.GroupSrcArtifactFilesByLangAction
create_envs¶
Create virtual environments for all envs discovered from the project's dependency-groups.
- Source:
finecode_extension_api.actions.CreateEnvsAction
install_envs¶
Install handler dependencies into virtualenvs.
- Source:
finecode_extension_api.actions.InstallEnvsAction
The python -m finecode prepare-envs CLI command runs create_envs and install_envs in sequence.
install_deps_in_env¶
Install dependencies into a specific environment.
- Source:
finecode_extension_api.actions.InstallDepsInEnvAction
dump_config¶
Dump the resolved configuration for a source artifact that includes FineCode configuration.
- Source:
finecode_extension_api.actions.DumpConfigAction
Also available as python -m finecode dump-config.
init_repository_provider¶
Initialize a repository provider (used in artifact publishing flows).
- Source:
finecode_extension_api.actions.InitRepositoryProviderAction
ingest_wal_to_store¶
Ingest write-ahead-log events from one or more generic sources into a durable store.
- Source:
finecode_extension_api.actions.IngestWalToStoreAction
Payload fields:
| Field | Type | Default | Description |
|---|---|---|---|
source_specs |
list[WalSourceSpec] |
Source definitions to ingest from | |
since_ts_iso |
str \| None |
None |
Ignore events older than this ISO8601 UTC timestamp |
store_uri |
ResourceUri \| None |
None |
Destination store URI. If omitted, handler chooses a default path |
WalSourceSpec fields:
| Field | Type | Default | Description |
|---|---|---|---|
source_id |
str |
Stable source identifier used in summaries | |
format |
str |
Source format, e.g. jsonl_events |
|
location_uri |
ResourceUri |
File or directory URI containing events | |
include_glob |
str \| None |
None |
Include pattern for directory scanning |
exclude_glob |
str \| None |
None |
Exclude pattern for directory scanning |
field_mapping |
dict[str, str] \| None |
None |
Optional canonical-to-source mapping (ts, event_type, run_id, action_name, payload) |
Result fields:
| Field | Type | Description |
|---|---|---|
schema_version |
int |
Result schema version |
source_summary |
list[SourceIngestSummary] |
Per-source ingest counters |
events_ingested |
int |
Successfully inserted event count |
events_skipped_duplicate |
int |
Duplicate event count |
events_failed_parse |
int |
Parse/normalization failure count |
first_event_ts_iso |
str \| None |
Earliest inserted event timestamp |
last_event_ts_iso |
str \| None |
Latest inserted event timestamp |
store_uri |
ResourceUri |
Final store URI |
warnings |
list[str] |
Non-fatal ingest warnings |
summarize_wal_logs (extension action)¶
Read write-ahead-log events directly from generic sources and compute run-level summaries and aggregate metrics.
- Source:
finecode_extension_api.actions.SummarizeWalLogsAction
This action is source-agnostic and does not require a database.
Payload fields:
| Field | Type | Default | Description |
|---|---|---|---|
source_specs |
list[WalSourceSpec] |
Source definitions to summarize | |
from_ts_iso |
str \| None |
None |
Optional lower timestamp bound (inclusive) |
to_ts_iso |
str \| None |
None |
Optional upper timestamp bound (inclusive) |
max_runs |
int |
1000 |
Maximum number of run summaries returned |
Result fields:
| Field | Type | Description |
|---|---|---|
schema_version |
int |
Result schema version |
discovered_sources |
list[WalSourceInfo] |
Source metadata used during scan |
run_summaries |
list[RunSummary] |
Per-run summary rows |
aggregate_metrics |
AggregateMetrics |
Global counters and duration percentiles |
warnings |
list[str] |
Non-fatal parse/filter warnings |
export_wal_timeline_from_logs (extension action)¶
Read write-ahead-log events directly from generic sources and generate a static HTML timeline.
- Source:
finecode_extension_api.actions.ExportWalTimelineFromLogsAction
This action is source-agnostic and does not require a database.
Payload fields:
| Field | Type | Default | Description |
|---|---|---|---|
source_specs |
list[WalSourceSpec] |
Source definitions to read | |
output_html_path |
ResourceUri |
Destination HTML file path | |
run_id_filter |
str \| None |
None |
Optional run-id filter |
from_ts_iso |
str \| None |
None |
Optional lower timestamp bound (inclusive) |
to_ts_iso |
str \| None |
None |
Optional upper timestamp bound (inclusive) |
max_events |
int |
20000 |
Maximum number of events rendered |
Result fields:
| Field | Type | Description |
|---|---|---|
schema_version |
int |
Result schema version |
output_html_path |
ResourceUri |
Path to generated HTML file |
events_rendered |
int |
Number of events written to timeline |
runs_included |
int |
Distinct run IDs included in output |
time_window |
TimeWindow |
Effective time filter window |
warnings |
list[str] |
Non-fatal parse/filter warnings |
serve_wal_explorer_from_store (extension action)¶
Start a read-only HTTP API over the WAL DuckDB store and serve until interrupted.
- Source:
finecode_extension_api.actions.ServeWalExplorerFromStoreAction - Default handler execution: sequential
Payload fields:
| Field | Type | Default | Description |
|---|---|---|---|
store_uri |
ResourceUri \| None |
None |
Path to the DuckDB store. Defaults to <venv>/state/finecode/wal_explorer/store.duckdb. |
host |
str |
"127.0.0.1" |
Interface to bind the HTTP server to. |
port |
int |
8765 |
Port number. If the default port is already occupied, the handler auto-selects a free port. |
read_only |
bool |
True |
Open the DuckDB store in read-only mode. |
Result fields:
| Field | Type | Description |
|---|---|---|
schema_version |
int |
Store schema version. |
base_url |
str |
Full base URL the server is listening on. |
bound_host |
str |
Resolved host after binding. |
bound_port |
int |
Resolved port after binding. |
store_uri |
ResourceUri |
Resolved store path used. |
warnings |
list[str] |
Non-fatal warnings. |
Endpoints:
| Path | Description |
|---|---|
GET /health |
Server status, schema version, event/run totals. |
GET /runs |
Run summaries. Query params: source_id, from_ts, to_ts, limit. |
GET /timeline |
Ordered event stream. Query params: run_id, source_id, from_ts, to_ts, event_type, limit. |
GET /metrics |
Aggregate counters and duration percentiles. |
GET /events |
Raw event rows. Query params: run_id, source_id, from_ts, to_ts, limit. |
The action runs until its invocation is cancelled. Cancellation triggers deterministic cleanup: HTTP server shutdown and DuckDB connection close.