workflows

package
v0.4.13 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 20, 2026 License: MIT Imports: 7 Imported by: 0

Documentation

Overview

Package workflows builds deterministic GoForj workflow guidance for Atlas.

Index

Constants

This section is empty.

Variables

View Source 
var WorkflowDocsMap = map[string][]DocReference{
	"goforj-add-http-route": {
		{Path: "applications/routes.md", Heading: "Where Routes Live"},
		{Path: "applications/controllers.md", Heading: "Controller Shape"},
		{Path: "core/wiring-recipes.md", Heading: "HTTP Controller"},
	},
	"goforj-add-app-command": {
		{Path: "applications/commands.md", Heading: "Make Commands"},
		{Path: "core/wiring-recipes.md", Heading: "Command"},
	},
	"goforj-add-job": {
		{Path: "async/jobs.md", Heading: "Generated Package"},
		{Path: "async/workers.md", Heading: "Runtime Boundary"},
	},
	"goforj-add-job-schedule": {
		{Path: "async/jobs.md", Heading: "Generated Package"},
		{Path: "async/scheduler.md", Heading: "Registry"},
		{Path: "async/events-vs-queues.md", Heading: "Default Recommendation"},
	},
	"goforj-add-schedule": {
		{Path: "async/scheduler.md", Heading: "Registry"},
		{Path: "operations/scheduler-processes.md", Heading: "Singleton Behavior"},
	},
	"goforj-add-event-workflow": {
		{Path: "async/events-vs-queues.md", Heading: "Default Recommendation"},
		{Path: "async/event-subscribers.md", Heading: "Where To Register"},
	},
	"goforj-add-data-resource": {
		{Path: "data/repositories.md", Heading: "Repository Shape"},
		{Path: "data/migrations.md", Heading: "Files"},
		{Path: "data/driver-selection.md", Heading: "Two Decisions"},
	},
	"goforj-wire-repair": {
		{Path: "core/reading-wire-errors.md", Heading: "Fast Checklist"},
		{Path: "core/wiring-recipes.md", Heading: "Quick Map"},
	},
	"goforj-debug-runtime": {
		{Path: "operations/logging.md", Heading: "Good Default Logs"},
		{Path: "operations/metrics.md", Heading: "Labels"},
		{Path: "operations/inspects.md", Heading: "What Inspects Capture"},
	},
	"goforj-multi-app-change": {
		{Path: "core/apps.md", Heading: "Use an app as a command prefix"},
		{Path: "core/app.md", Heading: "Named Apps"},
	},
	"goforj-frontend-change": {
		{Path: "frontend/starter-kits.md", Heading: "Starter Kits"},
		{Path: "core/local-first-development.md", Heading: "forj dev"},
	},
	"goforj-validate-change": {
		{Path: "testing/overview.md", Heading: "Testing Layers"},
		{Path: "reference/generation-commands.md", Heading: "Full Build Pipeline"},
	},
}

WorkflowDocsMap maps workflow ids to the docs sections agents should read first.

Functions

func Classify 

func Classify(task string) string

Classify maps task text to a stable GoForj workflow id.

func ClassifyAll added in v0.4.13 

func ClassifyAll(task string) []string

ClassifyAll returns every independently useful workflow present in a broad task.

func ConfidenceForRuntimeEvidence 

func ConfidenceForRuntimeEvidence(snapshot RuntimeSnapshotResult) string

ConfidenceForRuntimeEvidence summarizes how complete a runtime snapshot is.

Types

type CommandAdviceRequest 

type CommandAdviceRequest struct {
	Task     string `json:"task"`
	App      string `json:"app,omitempty"`
	Resource string `json:"resource,omitempty"`
}

CommandAdviceRequest asks Atlas for the preferred GoForj command for a task.

type CommandAdviceResult 

type CommandAdviceResult struct {
	WorkflowID string `json:"workflow_id"`
	App        string `json:"app"`
	Command    string `json:"command"`
	Reason     string `json:"reason"`
}

CommandAdviceResult describes one preferred command.

func CommandAdvice 

func CommandAdvice(ctx Context, req CommandAdviceRequest) (CommandAdviceResult, bool)

CommandAdvice returns the most specific make or validation command for a task.

type Context 

type Context struct {
	Project     project.Project                  `json:"project"`
	Inventory   Inventory                        `json:"inventory,omitempty"`
	Connections []diagnostics.DatabaseConnection `json:"connections,omitempty"`
	Overlays    []string                         `json:"overlays,omitempty"`
}

Context contains the local project facts used by workflow helpers.

type DebugPlanResult 

type DebugPlanResult struct {
	App             string          `json:"app"`
	Runtime         string          `json:"runtime,omitempty"`
	Path            string          `json:"path,omitempty"`
	RouteName       string          `json:"route_name,omitempty"`
	Confidence      string          `json:"confidence"`
	Steps           []DebugPlanStep `json:"steps"`
	MissingEvidence []string        `json:"missing_evidence,omitempty"`
}

DebugPlanResult recommends read-only next steps from a runtime snapshot.

func DebugPlan 

func DebugPlan(snapshot RuntimeSnapshotResult) DebugPlanResult

DebugPlan builds next read-only inspection steps from available runtime evidence.

type DebugPlanStep 

type DebugPlanStep struct {
	Tool     string `json:"tool"`
	Purpose  string `json:"purpose"`
	Required bool   `json:"required"`
}

DebugPlanStep describes one read-only inspection step.

type DocReference 

type DocReference struct {
	Path    string `json:"path"`
	Heading string `json:"heading,omitempty"`
	Reason  string `json:"reason,omitempty"`
}

DocReference points an agent at a focused docs section.

type DocsSection 

type DocsSection struct {
	Reference DocReference      `json:"reference"`
	Section   atlasdocs.Section `json:"section,omitempty"`
	Found     bool              `json:"found"`
}

DocsSection contains one bounded docs section for a workflow.

type DocsSectionPackResult 

type DocsSectionPackResult struct {
	WorkflowID string                  `json:"workflow_id"`
	Manifest   atlasdocs.Manifest      `json:"manifest,omitempty"`
	Alignment  *VersionAlignmentResult `json:"alignment,omitempty"`
	Sections   []DocsSection           `json:"sections"`
}

DocsSectionPackResult contains docs sections in workflow reading order.

func DocsSectionPack 

func DocsSectionPack(ctx context.Context, provider atlasdocs.Provider, workflowID string, task string, tokenLimit int) (DocsSectionPackResult, error)

DocsSectionPack reads the bounded docs sections for a workflow or task.

type EvalCheck 

type EvalCheck struct {
	Name    string `json:"name"`
	Passed  bool   `json:"passed"`
	Details string `json:"details,omitempty"`
}

EvalCheck describes one scored expectation for a workflow fixture.

type EvalFixture 

type EvalFixture struct {
	Name                string   `json:"name"`
	Task                string   `json:"task"`
	App                 string   `json:"app,omitempty"`
	WantWorkflowID      string   `json:"want_workflow_id"`
	WantWorkflowIDs     []string `json:"want_workflow_ids,omitempty"`
	WantCommandPart     string   `json:"want_command_part,omitempty"`
	WantCommandParts    []string `json:"want_command_parts,omitempty"`
	WantFilePart        string   `json:"want_file_part,omitempty"`
	WantFileParts       []string `json:"want_file_parts,omitempty"`
	WantDocsPath        string   `json:"want_docs_path,omitempty"`
	WantDocsPaths       []string `json:"want_docs_paths,omitempty"`
	WantTools           []string `json:"want_tools,omitempty"`
	WantValidationParts []string `json:"want_validation_parts,omitempty"`
	WantWarningParts    []string `json:"want_warning_parts,omitempty"`
	AvoidFileParts      []string `json:"avoid_file_parts,omitempty"`
}

EvalFixture describes a deterministic workflow planning scenario.

func EvalFixtures 

func EvalFixtures() []EvalFixture

EvalFixtures returns common agent tasks used to guard workflow quality.

func RegressionFixtures 

func RegressionFixtures() []EvalFixture

RegressionFixtures returns workflow cases captured from failed scorecard runs.

type EvalResult 

type EvalResult struct {
	Name       string            `json:"name"`
	Passed     bool              `json:"passed"`
	Plan       PlanResult        `json:"plan"`
	Checks     []EvalCheck       `json:"checks,omitempty"`
	Failures   []string          `json:"failures,omitempty"`
	Transcript []TranscriptEntry `json:"transcript,omitempty"`
}

EvalResult describes one deterministic workflow fixture result.

type FilePolicyRequest 

type FilePolicyRequest struct {
	Path        string          `json:"path"`
	Task        string          `json:"task,omitempty"`
	Resource    string          `json:"resource,omitempty"`
	WorkflowIDs []string        `json:"workflow_ids,omitempty"`
	Project     project.Project `json:"project,omitempty"`
	ProjectRoot string          `json:"project_root,omitempty"`
	Rules       []OwnershipRule `json:"rules,omitempty"`
}

FilePolicyRequest asks Atlas to classify a project path.

type FilePolicyResult 

type FilePolicyResult struct {
	Path            string   `json:"path"`
	Classification  string   `json:"classification"`
	Editable        bool     `json:"editable"`
	PreferredAction string   `json:"preferred_action"`
	ChangeThrough   string   `json:"change_through,omitempty"`
	App             string   `json:"app,omitempty"`
	FrontendKit     string   `json:"frontend_kit,omitempty"`
	Owner           string   `json:"owner,omitempty"`
	MatchedRule     string   `json:"matched_rule,omitempty"`
	Reason          string   `json:"reason"`
	Warnings        []string `json:"warnings,omitempty"`
}

FilePolicyResult describes how agents should treat a project path.

func FilePolicies 

func FilePolicies(req FilePolicyRequest, paths []string) []FilePolicyResult

FilePolicies classifies a list of planned files with the same ownership model.

func FilePolicy 

func FilePolicy(req FilePolicyRequest) FilePolicyResult

FilePolicy classifies whether a path is generated, app-owned, or user-owned.

type Inventory 

type Inventory struct {
	Routes     map[string][]string `json:"routes,omitempty"`
	Schedules  map[string][]string `json:"schedules,omitempty"`
	Commands   map[string][]string `json:"commands,omitempty"`
	Queues     []string            `json:"queues,omitempty"`
	Caches     []string            `json:"caches,omitempty"`
	Disks      []string            `json:"disks,omitempty"`
	EventBuses []string            `json:"event_buses,omitempty"`
	Resources  []ResourceLink      `json:"resources,omitempty"`
}

Inventory contains app-aware project facts used by workflow planning.

type OwnershipRule 

type OwnershipRule struct {
	Pattern         string `json:"pattern"`
	Classification  string `json:"classification"`
	Editable        bool   `json:"editable"`
	PreferredAction string `json:"preferred_action,omitempty"`
	ChangeThrough   string `json:"change_through,omitempty"`
	Reason          string `json:"reason,omitempty"`
}

OwnershipRule describes a project-specific path ownership override.

type PlanRequest 

type PlanRequest struct {
	Task string `json:"task"`
	App  string `json:"app,omitempty"`
}

PlanRequest asks Atlas for a workflow plan for a task.

type PlanResult 

type PlanResult struct {
	WorkflowID   string             `json:"workflow_id"`
	WorkflowIDs  []string           `json:"workflow_ids,omitempty"`
	Segments     []WorkflowSegment  `json:"segments,omitempty"`
	Steps        []PlanStep         `json:"steps,omitempty"`
	App          string             `json:"app"`
	Tools        []string           `json:"tools,omitempty"`
	Commands     []string           `json:"commands,omitempty"`
	Files        []string           `json:"files,omitempty"`
	Ownership    []FilePolicyResult `json:"ownership,omitempty"`
	Docs         []DocReference     `json:"docs,omitempty"`
	Overlays     []string           `json:"overlays,omitempty"`
	Verification []ValidationStep   `json:"verification,omitempty"`
	Warnings     []string           `json:"warnings,omitempty"`
}

PlanResult describes the framework workflow an agent should follow.

func Plan 

func Plan(ctx Context, req PlanRequest) (PlanResult, bool)

Plan returns a deterministic workflow plan for a GoForj task.

type PlanStep added in v0.4.13 

type PlanStep struct {
	Order      int    `json:"order"`
	WorkflowID string `json:"workflow_id"`
	Action     string `json:"action"`
	Purpose    string `json:"purpose"`
}

PlanStep records one ordered prerequisite or implementation action.

type RegistrationPoint 

type RegistrationPoint struct {
	Kind              string   `json:"kind"`
	App               string   `json:"app"`
	Files             []string `json:"files"`
	ComponentRequired string   `json:"component_required,omitempty"`
}

RegistrationPoint describes one app-owned registration surface.

type RegistrationResult 

type RegistrationResult struct {
	App    string              `json:"app"`
	Points []RegistrationPoint `json:"points"`
}

RegistrationResult describes registration surfaces for one app.

func RegistrationPoints 

func RegistrationPoints(p project.Project, appName string) (RegistrationResult, bool)

RegistrationPoints returns app-owned registration surfaces for one app.

type ResourceInventory 

type ResourceInventory struct {
	Apps        []project.App                    `json:"apps"`
	Components  []string                         `json:"components,omitempty"`
	FrontendKit string                           `json:"frontend_kit,omitempty"`
	Routes      map[string][]string              `json:"routes,omitempty"`
	Schedules   map[string][]string              `json:"schedules,omitempty"`
	Commands    map[string][]string              `json:"commands,omitempty"`
	Queues      []string                         `json:"queues,omitempty"`
	Caches      []string                         `json:"caches,omitempty"`
	Disks       []string                         `json:"disks,omitempty"`
	EventBuses  []string                         `json:"event_buses,omitempty"`
	Resources   []ResourceLink                   `json:"resources,omitempty"`
	Databases   []diagnostics.DatabaseConnection `json:"databases,omitempty"`
	Categories  []string                         `json:"categories,omitempty"`
}

ResourceInventory describes named and runtime resources visible to Atlas.

func Resources 

func Resources(ctx Context) ResourceInventory

Resources returns project resources visible to Atlas planning. 

type ResourceLink struct {
	ID       string `json:"id"`
	Label    string `json:"label"`
	URL      string `json:"url,omitempty"`
	Category string `json:"category,omitempty"`
	Source   string `json:"source,omitempty"`
	App      string `json:"app,omitempty"`
	Runtime  string `json:"runtime,omitempty"`
	Health   string `json:"health,omitempty"`
	Auth     string `json:"auth,omitempty"`
	Owner    string `json:"owner,omitempty"`
}

ResourceLink describes a dashboard, app URL, or operator-facing resource.

func FilterResourcesForRuntime 

func FilterResourcesForRuntime(resources []ResourceLink, app string, runtime string) []ResourceLink

FilterResourcesForRuntime returns links that are useful while debugging a runtime.

type RuntimeSnapshotRequest 

type RuntimeSnapshotRequest struct {
	App        string `json:"app,omitempty"`
	Runtime    string `json:"runtime,omitempty"`
	Path       string `json:"path,omitempty"`
	RouteName  string `json:"route_name,omitempty"`
	TimeWindow string `json:"time_window,omitempty"`
	Limit      int    `json:"limit,omitempty"`
}

RuntimeSnapshotRequest describes local runtime evidence the agent wants to inspect.

type RuntimeSnapshotResult 

type RuntimeSnapshotResult struct {
	App             string                        `json:"app"`
	Runtime         string                        `json:"runtime,omitempty"`
	Path            string                        `json:"path,omitempty"`
	RouteName       string                        `json:"route_name,omitempty"`
	TimeWindow      string                        `json:"time_window,omitempty"`
	Routes          []string                      `json:"routes,omitempty"`
	Resources       []ResourceLink                `json:"resources,omitempty"`
	Logs            []diagnostics.LogEntry        `json:"logs,omitempty"`
	LastError       diagnostics.LogEntry          `json:"last_error,omitempty"`
	LastErrorFound  bool                          `json:"last_error_found"`
	AbsoluteURL     string                        `json:"absolute_url,omitempty"`
	BrowserLogs     []diagnostics.BrowserLogEntry `json:"browser_logs,omitempty"`
	Metrics         diagnostics.MetricsMetadata   `json:"metrics,omitempty"`
	MissingEvidence []string                      `json:"missing_evidence,omitempty"`
	Confidence      string                        `json:"confidence"`
}

RuntimeSnapshotResult combines safe local evidence for one app/runtime.

type ScenarioGuideResult 

type ScenarioGuideResult struct {
	Query     string         `json:"query"`
	Scenarios []DocReference `json:"scenarios"`
}

ScenarioGuideResult points agents at verified scenario docs.

func ScenarioGuide 

func ScenarioGuide(ctx context.Context, provider atlasdocs.Provider, query string) (ScenarioGuideResult, error)

ScenarioGuide returns verified scenario references relevant to a query.

type Scorecard 

type Scorecard struct {
	Total   int          `json:"total"`
	Passed  int          `json:"passed"`
	Failed  int          `json:"failed"`
	Results []EvalResult `json:"results"`
}

Scorecard summarizes workflow fixture quality.

func RunEvalFixtures 

func RunEvalFixtures(ctx Context, captureTranscript bool) Scorecard

RunEvalFixtures evaluates workflow planning against deterministic fixtures.

type TranscriptEntry 

type TranscriptEntry struct {
	Step    string `json:"step"`
	Details string `json:"details,omitempty"`
}

TranscriptEntry is one optional workflow-eval trace event.

type ValidationResult 

type ValidationResult struct {
	App      string           `json:"app"`
	Steps    []ValidationStep `json:"steps"`
	Warnings []string         `json:"warnings,omitempty"`
}

ValidationResult describes the checks Atlas recommends for a task.

func ValidationPlan 

func ValidationPlan(ctx Context, req PlanRequest) ValidationResult

ValidationPlan returns task-aware verification commands.

type ValidationStep 

type ValidationStep struct {
	Command  string `json:"command"`
	Purpose  string `json:"purpose"`
	Required bool   `json:"required"`
}

ValidationStep describes one verification command or Atlas inspection.

type VersionAlignmentResult 

type VersionAlignmentResult struct {
	ProjectGoForjVersion string             `json:"project_goforj_version,omitempty"`
	AtlasVersion         string             `json:"atlas_version,omitempty"`
	DocsVersion          string             `json:"docs_version,omitempty"`
	DocsRef              string             `json:"docs_ref,omitempty"`
	DocsRevision         string             `json:"docs_revision,omitempty"`
	DocsCommit           string             `json:"docs_commit,omitempty"`
	Aligned              bool               `json:"aligned"`
	Warnings             []VersionWarning   `json:"warnings,omitempty"`
	Manifest             atlasdocs.Manifest `json:"manifest"`
}

VersionAlignmentResult compares project, Atlas, and docs versions.

func VersionAlignment 

func VersionAlignment(p project.Project, atlasVersion string, manifest atlasdocs.Manifest) VersionAlignmentResult

VersionAlignment compares project version facts with docs metadata.

type VersionWarning 

type VersionWarning struct {
	Code    string `json:"code"`
	Message string `json:"message"`
}

VersionWarning describes one actionable version mismatch.

type WireDiagnostic 

type WireDiagnostic struct {
	Category     string   `json:"category"`
	Message      string   `json:"message"`
	MissingType  string   `json:"missing_type,omitempty"`
	Consumer     string   `json:"consumer,omitempty"`
	ProviderSet  string   `json:"provider_set,omitempty"`
	LikelyFiles  []string `json:"likely_files,omitempty"`
	SuggestedFix string   `json:"suggested_fix"`
}

WireDiagnostic describes a likely Wire failure category and fix.

func DiagnoseWire 

func DiagnoseWire(output string) []WireDiagnostic

DiagnoseWire classifies common Wire error output.

type WorkflowSegment added in v0.4.13 

type WorkflowSegment struct {
	WorkflowID string         `json:"workflow_id"`
	Commands   []string       `json:"commands,omitempty"`
	Files      []string       `json:"files,omitempty"`
	Docs       []DocReference `json:"docs,omitempty"`
	Warnings   []string       `json:"warnings,omitempty"`
	Steps      []PlanStep     `json:"steps,omitempty"`
}

WorkflowSegment preserves one concern inside a compositional application plan.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.