{"id":51778190,"url":"https://github.com/puffball1567/flowcaptain","last_synced_at":"2026-07-20T08:03:07.392Z","repository":{"id":370935423,"uuid":"1287041942","full_name":"puffball1567/flowcaptain","owner":"puffball1567","description":"Top-level orchestration and CLI layer for the FlowBrigade toolkit.","archived":false,"fork":false,"pushed_at":"2026-07-12T04:22:37.000Z","size":41,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-12T05:09:51.265Z","etag":null,"topics":["flow-analysis","flowbrigade","flowbrigade-toolkit","nim","observability","pdca","workflow"],"latest_commit_sha":null,"homepage":null,"language":"Nim","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/puffball1567.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-07-02T10:22:14.000Z","updated_at":"2026-07-12T03:14:47.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/puffball1567/flowcaptain","commit_stats":null,"previous_names":["puffball1567/flowcaptain"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/puffball1567/flowcaptain","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puffball1567%2Fflowcaptain","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puffball1567%2Fflowcaptain/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puffball1567%2Fflowcaptain/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puffball1567%2Fflowcaptain/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/puffball1567","download_url":"https://codeload.github.com/puffball1567/flowcaptain/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puffball1567%2Fflowcaptain/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35678471,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"ssl_error","status_checked_at":"2026-07-20T02:08:09.736Z","response_time":111,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["flow-analysis","flowbrigade","flowbrigade-toolkit","nim","observability","pdca","workflow"],"created_at":"2026-07-20T08:03:06.854Z","updated_at":"2026-07-20T08:03:07.387Z","avatar_url":"https://github.com/puffball1567.png","language":"Nim","funding_links":[],"categories":[],"sub_categories":[],"readme":"# FlowCaptain\n\nTop-level orchestration and reporting layer for the FlowBrigade Toolkit.\n\n## Intended Role\n\nFlowCaptain coordinates the FlowBrigade Toolkit components:\n\n- FlowDependency for graph structure\n- FlowWorkRunner for execution\n- FlowBrigade for runtime control\n- FlowLogbook for records\n- FlowSurveyor for analysis\n- FlowGarage for report bundles and package manifests\n\n## v0.1.0 Scope\n\nThe first target scenario is `daily-report`:\n\n- define a graph\n- validate it\n- dry-run the execution order with FlowDependency\n- run or simulate work with FlowWorkRunner\n- record events\n- analyze bottlenecks and critical path\n- compare at least two variants\n- generate browser-readable HTML and Markdown reports\n- generate Mermaid diagrams as secondary artifacts\n- generate a package manifest\n- import framework adapter JSONL events\n- provide a thin Laravel-compatible adapter for command, queue, scheduler, and\n  batch instrumentation\n- validate shared FlowBrigade Toolkit ids\n- compare plan structure changes before and after optimization\n- score flow health for reliability and optimization readiness\n\n## Install\n\nFlowCaptain requires Nim 2.2 or newer.\n\nAfter release, install it with Nimble:\n\n```bash\nnimble install flowcaptain\n```\n\nFlowCaptain depends on the FlowBrigade Toolkit libraries. Until every toolkit\npackage is available from the Nimble package index, the package metadata points\nunregistered toolkit dependencies at their GitHub repositories.\n\nWhen working from this repository, the Nimble tasks use the local `deps/`\nworkspace paths:\n\n```bash\nnimble test\nnimble examples\nnimble eventReportExample\nnimble laravelAdapterExample\nnimble leak\n```\n\n`nimble leak` builds the ARC release leak probe and runs it under Valgrind,\nfailing on definite or indirect leaks.\n\nThe latest verification record is kept in\n[docs/VERIFICATION.md](docs/VERIFICATION.md).\n\n## Toolkit Execution\n\nFlowCaptain can execute a plan through the lower-level toolkit pieces:\n\n```nim\nimport flowcaptain\n\nvar plan = initCaptainPlan(\"daily\", \"Daily\")\nplan.nodes.add(node(\"extract\", \"Extract\", expectedMs = 10))\nplan.nodes.add(node(\"publish\", \"Publish\", expectedMs = 20))\nplan.edges.add(edge(\"extract-publish\", \"extract\", \"publish\"))\n\nlet outcome = plan.executeWithToolkit().complete()\n```\n\n`executeWithToolkit` uses FlowDependency for dependency-ready batches and\nFlowWorkRunner for execution. For production work, pass a\n`WorkExecutorRegistry` with executors for each node.\n\n## Public Integration API\n\nFlowCaptain is the public bridge for the FlowBrigade Toolkit. External\nadapters and future language bindings do not need to call every lower-level\ntoolkit package directly. They can call FlowCaptain's integration API and let\nFlowCaptain delegate to FlowDependency, FlowWorkRunner, FlowLogbook,\nFlowSurveyor, and FlowGarage, while preserving FlowBrigade-compatible retry\nand control signals for reports and future policy bridges.\n\n```nim\nimport flowcaptain\n\nlet plan = loadPlanJson(readFile(\"plan.json\"))\nlet events = importEventsJsonl(readFile(\"events.jsonl\"))\n\nlet outcome = analyzeAdapterEvents(plan, events)\nlet output = generateReportsFromAdapterEvents(plan, events)\n```\n\nThe integration API intentionally keeps responsibilities separate:\n\n- FlowDependency remains responsible for graph structure and dependency-ready\n  batches.\n- FlowWorkRunner remains responsible for execution integration.\n- FlowSurveyor remains responsible for bottleneck, wait, failure, and\n  operational analysis.\n- FlowGarage remains responsible for report bundle conversion.\n- FlowBrigade remains the policy/runtime-control layer; FlowCaptain currently\n  carries compatible retry and control evidence through outcomes and reports.\n- FlowCaptain coordinates these pieces and exposes stable entry points for\n  adapters, CLIs, and future C ABI bindings.\n\nUseful entry points include:\n\n- `loadPlanJson` / `savePlanJson`\n- `normalizePlan` / `validatePlan` / `validatePlanJson`\n- `dryRunPlan` / `dependencyBatches`\n- `executePlan` / `simulatePlan`\n- `importEventsJsonl` / `exportEventsJsonl`\n- `validateAdapterContract` / `validateAdapterContractJsonl`\n- `analyzeAdapterEvents` / `generateReportsFromAdapterEvents`\n- `generateReports` / `writeReports`\n- `diffPlanJson` / `comparePlanVariants`\n- `historySnapshot` / `historySnapshotsJsonLines` / `historyTrend`\n- `appendHistorySnapshotFile` / `loadHistorySnapshotsFile` for local JSONL history\n- `appendHistorySnapshotSqlite` / `loadHistorySnapshotsSqlite` for SQLite history\n- `flowHealth` / `flowHealthJson`\n- `metricEventsFor` / `metricEventsJsonLinesFor`\n- `flowDiagram` / `structureDiagram` / `comparisonDiagram`\n- `validateControlBridge` / `allowControlPolicy` / `inspectControlPolicy` for FlowBrigade policy bridges\n\nThis means framework adapters should not stop at writing JSONL. A complete\nadapter can collect safe events, build or load a plan, call FlowCaptain through\nthe public API or CLI, and produce the same reports, metrics, health score,\nvariant comparison, and artifacts available to native Nim users.\n\n## Integration Primitives\n\nFlowCaptain exposes small primitives that are useful across the toolkit:\n\n- `checkSharedId` and `normalizeSharedId` keep `flowId`, `runId`, `nodeId`,\n  `edgeId`, `artifactId`, and `policyId` compatible across repositories.\n- `diffPlans` reports node and edge changes between two flow definitions,\n  including breaking removals and wait-on changes.\n- `health` converts run, survey, retry, wait, and critical-path signals into a\n  single score plus reasons.\n\nThese are deliberately independent from any specific web framework or workflow\nengine. They are meant to make FlowCaptain useful for both executed flows and\nexternally observed business flows.\n\n\n## Flow Investigation Method\n\nFlowCaptain is also a flow investigation tool. It can start from hearing notes,\nexisting jobs, methods, database tables, logs, and adapter events, then help an\nanalyst decide which nodes to connect, measure, split, or refine.\n\nSee:\n\n- [docs/METHODOLOGY.md](docs/METHODOLOGY.md)\n- [docs/NODE_DESIGN_GUIDE.md](docs/NODE_DESIGN_GUIDE.md)\n- [docs/INVESTIGATION_WORKFLOW.md](docs/INVESTIGATION_WORKFLOW.md)\n\n## Run History\n\nFlowCaptain can turn each analyzed run into a compact history snapshot. Callers\ncan store the JSONL in a database, object storage, or a batch artifact directory\nand compare the latest run with the previous run.\n\n```nim\nlet outcome = analyzeAdapterEvents(plan, events)\nlet snapshot = historySnapshot(outcome, runId = \"billing-2026-07-13\")\nlet jsonl = historySnapshotsJsonLines(@[snapshot])\nappendHistorySnapshotFile(\"reports/history.jsonl\", snapshot)\nappendHistorySnapshotSqlite(\"reports/history.sqlite3\", snapshot)\n```\n\n`historyTrend` compares the latest two snapshots and reports critical-path,\nwork, wait, retry, failure, health, cycle-time, throughput, and yield changes.\nThis is the core PDCA loop: record a run, change the flow, record the next run,\nthen check whether the whole flow improved or merely moved the bottleneck.\n\n## Adapter Events\n\nFramework adapters can start with lightweight JSON Lines events instead of\nembedding FlowCaptain deeply into application code. This is intended for web\nbatch, job, queue, and scheduled-task instrumentation.\n\n```json\n{\"schemaVersion\":1,\"eventType\":\"nodeFinished\",\"flowId\":\"billing\",\"runId\":\"run-1\",\"variantId\":\"A\",\"nodeId\":\"calculate\",\"durationMs\":850,\"status\":\"succeeded\",\"retryCount\":1}\n```\n\nFlowCaptain can parse these events with `parseAdapterEventsJsonLines`, validate\nthe shared adapter contract with `validateAdapterContract`, and turn them into\nan analyzable outcome with `outcomeFromAdapterEvents`.\n\nThe CLI can generate browser-readable reports from a plan JSON and adapter\nevent JSONL:\n\n```bash\nnimble eventReportExample\n```\n\nSee [docs/ADAPTER_EVENTS.md](docs/ADAPTER_EVENTS.md) for the event format,\ncompatibility contract, production notes, and adapter order.\n\nPlanned framework adapter order:\n\n```text\nLaravel, Symfony, Express, NestJS, Fastify, Prologue, FastAPI, Spring Boot\n```\n\nThe first thin adapter is available under\n[adapters/laravel](adapters/laravel). It emits JSONL events from Laravel-style\ncommands, queue jobs, schedulers, and batch segments without capturing payloads.\n\nYou can run the Laravel adapter smoke example and generate a FlowCaptain report:\n\n```bash\nnimble laravelAdapterExample\n```\n\n## Human-Checkable Output\n\nFlowCaptain should make example results easy to inspect. A user should be able\nto run the example and inspect:\n\n- `captain-report.md`\n- `captain-report.html`\n- `flow.mmd`\n- `structure.mmd`\n- `comparison.mmd`\n- `manifest.json`\n\nThe HTML report is the easiest local inspection target because it opens directly\nin a browser without Mermaid tooling. The generated reports should show:\n\n- overall status\n- flow diagram\n- structure diagram\n- timeline\n- bottlenecks\n- failures and retries\n- variant comparison\n- recommendation\n- generated artifacts\n\n## Dependencies and Notices\n\nFlowCaptain uses FlowSurveyor as the analysis provider for generated reports.\nDependency license notes are kept in\n[DEPENDENCY_NOTICES.md](DEPENDENCY_NOTICES.md).\n\n## Changelog\n\nRelease notes are kept in [CHANGELOG.md](CHANGELOG.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpuffball1567%2Fflowcaptain","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpuffball1567%2Fflowcaptain","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpuffball1567%2Fflowcaptain/lists"}