trak_flow 0.1.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 665da8b32b7c217ef2c5b0755caa9db4d9fd18fa6d9020f3b81f760f5a736c1b
-  data.tar.gz: 2bc92ce53419eedd2fa9e619a76eb0100faaaf49fe8c66dad01007d430f71cf3
+  metadata.gz: 2606b6f366413bd7f63ff4052533e8786973b0c94418d82a3f51a1d70926c46b
+  data.tar.gz: 38d4bc84e1a7948342ab828d42c2c1b9cb1332ebc876554b7bbb310d3d26f8d3
 SHA512:
-  metadata.gz: 6db8403e94db89fc472ba3feeae33e577c7b541630693f0f0365bd045e8d469e51c9cd86194e4ae75b0cc52edb26edff4109d9b93be3e351164875c1f0b631ee
-  data.tar.gz: f14732aaa2058255ed1111dc0557025a613b0e2e3c6abce66eb3913b63c2618be2e7969532258ab0be60fbc0a90b6ec6f3f62cd0c6c4299dc65f27c62db721ba
+  metadata.gz: 0f0823fcb8d829781394546d5c494584a038314b4a9719a635150f6acea97b0302bd447effa6e5eb68018afb25ec4ea33b8092f0844bcec33cca77e1205318a9
+  data.tar.gz: 32de4536ea66637a5f4c0d8d0bdc3a016e63cf93b4064a850acaa094819b960d9a25603edceef74e7d2d577d3cf2923cf2d0f2a60c4131635815a343aa10e03d

data/.fasterer.yml

@@ -0,0 +1,10 @@
+# Fasterer configuration for trak_flow.
+speedups:
+  # Conflicts with RuboCop's Style/RedundantFetchBlock, which wins here:
+  # the flagged defaults are frozen literals, so the block form saves no
+  # allocation. Only expensive defaults would justify the block.
+  fetch_with_argument_vs_block: false
+  # Rejected on purpose: rewriting readable each_with_index line parsing
+  # (Jsonl#read_entities) as a manual while loop trades clarity for a
+  # micro-optimization in IO-bound code.
+  each_with_index_vs_while: false

data/.loki

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+# trak_flow — distributed task tracking system for Robots (CLI + MCP server).
+
+# Shared MadBomber-level per-gem tasks (lifecycle, quality, git, docs).
+# import_up walks up from this repo until it finds madbomber/dev/.
+# Imported selectively — not "dev/*.loki" — so quality_rails.loki's
+# Rails-only gates (Brakeman, RailsBestPractices, ActiveRecordDoctor)
+# stay out of this non-Rails gem's quality run.
+import_up "dev/gem_tasks.loki"
+import_up "dev/quality.loki"
+import_up "dev/git.loki"
+import_up "dev/doc_tasks.loki"
+
+class Tasks
+  @@gem_name ||= "trak_flow".freeze
+
+  header "trak_flow v#{gem_version} — distributed task tracking for Robots"
+
+  desc "Run tests and RuboCop (rake default)"
+  def all
+    sh "bundle exec rake"
+  end
+
+  desc "Run the tf CLI (pass through arguments, e.g. asgard tf list)"
+  def tf(*args)
+    sh "bundle exec bin/tf #{args.join(' ')}"
+  end
+
+  desc "Start the TrakFlow MCP server"
+  def mcp(*args)
+    sh "bundle exec bin/tf_mcp #{args.join(' ')}", exec: true
+  end
+end

data/.reek.yml

@@ -0,0 +1,161 @@
+---
+# Reek configuration for trak_flow, following the sqa_project/.reek.yml
+# conventions used across the madbomber workspace.
+detectors:
+
+  # Disabled: public methods are documented via comments above the method,
+  # not a module-level comment.
+  IrresponsibleModule:
+    enabled: false
+
+  # Disabled: private helpers that don't reference self are fine where they are.
+  UtilityFunction:
+    enabled: false
+
+  # Disabled: respond_to? duck-typing is intentional.
+  ManualDispatch:
+    enabled: false
+
+  # Disabled: attr_accessor is standard Ruby; public attributes are a design choice.
+  Attribute:
+    enabled: false
+
+  # Disabled: bang methods without non-bang counterparts are common.
+  MissingSafeMethod:
+    enabled: false
+
+  # Disabled: explicit nil checks are idiomatic Ruby.
+  NilCheck:
+    enabled: false
+
+  # Disabled: in this codebase the "envied" receivers are db handles, option
+  # hashes, and IO objects — the suggested "move it to another class" is not
+  # applicable to a Sequel dataset or a parsed-JSON hash.
+  FeatureEnvy:
+    enabled: false
+
+  # Disabled: config-driven dispatch (error_policy, orphan_handling) is this
+  # gem's deliberate API style — a case over a policy string.
+  ControlParameter:
+    enabled: false
+
+  # Disabled: boolean keyword flags (ephemeral:, include_closed:, ...) are
+  # idiomatic Ruby and part of the public API.
+  BooleanParameter:
+    enabled: false
+
+  # Disabled: mirrors the RuboCop Lint/UnusedMethodArgument setting — args
+  # kept for API/documentation shape.
+  UnusedParameters:
+    enabled: false
+
+  # Default is 1 — two-deep iteration (a hash of arrays, rows of columns) is
+  # idiomatic Ruby.
+  NestedIterators:
+    max_allowed_nesting: 2
+
+  # Default is 1 — fires whenever a method is called even twice. Raise to 2.
+  # Excluded: the `dataset = dataset.where(...) if ...` filter chain and the
+  # three separate conditional alter_table migrations are the pattern itself,
+  # not accidental repetition.
+  DuplicateMethodCall:
+    max_calls: 2
+    exclude:
+      - "TrakFlow::Storage::Database#apply_date_filters"
+      - "TrakFlow::Storage::Database#migrate_schema_if_needed!"
+
+  # Default is 5 — too tight for orchestrator/dispatch methods; flog (see
+  # dev/quality.loki) is the blocking complexity gate, so raw statement count
+  # only needs to catch outliers. Excluded: the Sequel schema DSL and the
+  # migration steps are one statement per column/index — flat and declarative.
+  TooManyStatements:
+    max_statements: 15
+    exclude:
+      - "TrakFlow::Storage::Database#create_tasks_table"
+      - "TrakFlow::Storage::Database#migrate_schema_if_needed!"
+
+  # Disabled: flags the same guard reused across a class's methods (the
+  # options[:json] output mode, File.exist? checks, `if deleted.positive?`
+  # after deletes). Extracting these into state objects adds indirection
+  # without removing the underlying condition.
+  RepeatedConditional:
+    enabled: false
+
+  # Default is 3 — too low for methods with several named inputs. The MCP
+  # tool #call methods mirror their declared MCP input schemas verbatim.
+  LongParameterList:
+    max_params: 5
+    overrides:
+      initialize:
+        max_params: 8
+    exclude:
+      - "TrakFlow::Mcp::Tools::TaskCreate#call"
+      - "TrakFlow::Mcp::Tools::TaskUpdate#call"
+
+  # Default is 15; CLI-command classes legitimately carry more methods
+  # after complexity-driven extraction. Excluded: Database is the single
+  # facade over all Sequel access; CLI is the Thor command surface.
+  TooManyMethods:
+    max_methods: 25
+    exclude:
+      - "TrakFlow::Storage::Database"
+      - "TrakFlow::CLI"
+
+  # Default is 4 — too low for state-heavy objects.
+  TooManyInstanceVariables:
+    max_instance_variables: 20
+
+  TooManyConstants:
+    max_constants: 8
+
+  DataClump:
+    max_copies: 2
+    min_clump_size: 3
+
+  # Accept standard Ruby short-name conventions for limited-scope variables.
+  UncommunicativeVariableName:
+    accept:
+      - _
+      - a
+      - b
+      - c
+      - d
+      - e
+      - f
+      - h
+      - i
+      - k
+      - l
+      - m
+      - n
+      - p
+      - q
+      - r
+      - s
+      - t
+      - v
+
+  UncommunicativeParameterName:
+    accept:
+      - e
+      - i
+      - f
+      - k
+      - v
+      - t
+      - r
+      - s
+      - m
+      - n
+      - q
+      - b
+      - p
+
+exclude_paths:
+  - test
+  - examples
+  - docs
+  - coverage
+  - pkg
+  - site
+  - notes

data/.rubocop.yml

@@ -0,0 +1,187 @@
+AllCops:
+  NewCops: enable
+  SuggestExtensions: false
+  TargetRubyVersion: 4.0
+  Exclude:
+    - 'examples/**/*'
+    - 'docs/**/*'
+    - 'site/**/*'
+    - 'pkg/**/*'
+    - 'coverage/**/*'
+    - 'notes/**/*'
+    - 'vendor/**/*'
+
+# ── Style: disabled cops ───────────────────────────────────────────────────
+Style/StringLiterals:
+  Enabled: false
+
+Style/StringLiteralsInInterpolation:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+# Ruby 4.0 freezes string literals by default
+Style/FrozenStringLiteralComment:
+  Enabled: false
+
+Style/IfUnlessModifier:
+  Enabled: false
+
+Style/RescueModifier:
+  Enabled: false
+
+Style/TrivialAccessors:
+  Enabled: false
+
+Style/MultilineTernaryOperator:
+  Enabled: false
+
+Style/SafeNavigation:
+  Enabled: false
+
+Style/ClassAndModuleChildren:
+  Enabled: false
+
+Style/RescueStandardError:
+  Enabled: false
+
+# Both % and format/sprintf are acceptable
+Style/FormatString:
+  Enabled: false
+
+# String concatenation and interpolation are both acceptable
+Style/StringConcatenation:
+  Enabled: false
+
+# ── Layout ─────────────────────────────────────────────────────────────────
+Layout/LineLength:
+  Max: 140
+
+Layout/ExtraSpacing:
+  Enabled: false
+
+Layout/HashAlignment:
+  Enabled: false
+
+Layout/FirstHashElementIndentation:
+  Enabled: false
+
+Layout/EmptyLineAfterGuardClause:
+  Enabled: false
+
+# ── Naming ─────────────────────────────────────────────────────────────────
+# Archspec.rb is the filename the archspec tool requires (like Gemfile/Rakefile)
+Naming/FileName:
+  Exclude:
+    - 'Archspec.rb'
+
+# Single-char params (c, e, n) are acceptable throughout
+Naming/MethodParameterName:
+  Enabled: false
+
+Naming/RescuedExceptionsVariableName:
+  Enabled: false
+
+Naming/AccessorMethodName:
+  Enabled: false
+
+Naming/PredicatePrefix:
+  Enabled: false
+
+Naming/PredicateMethod:
+  Exclude:
+    - 'test/**/*'
+
+# ── Lint: relax noisy cops on intentional patterns ─────────────────────────
+Lint/EmptyBlock:
+  Exclude:
+    - 'test/**/*'
+
+# Library and framework methods commonly accept args for API/documentation purposes
+Lint/UnusedMethodArgument:
+  Enabled: false
+
+Lint/ConstantDefinitionInBlock:
+  Exclude:
+    - 'Rakefile'
+    - 'test/**/*'
+
+# ── Gemspec ────────────────────────────────────────────────────────────────
+# trak_flow declares dev deps directly in the gemspec (not a Gemfile group).
+# The Gemfile deliberately carries a few extra gems the gemspec must not:
+# ruby_llm/ruby_llm-mcp and puma/rackup are opt-in for consumers (see the
+# Gemfile comments), and fasterer/reek are quality-gate tools.
+Gemspec/DevelopmentDependencies:
+  EnforcedStyle: gemspec
+  AllowedGems:
+    - ruby_llm
+    - ruby_llm-mcp
+    - puma
+    - rackup
+    - fasterer
+    - reek
+
+Gemspec/RequiredRubyVersion:
+  Enabled: false
+
+Gemspec/OrderedDependencies:
+  Enabled: false
+
+# ── Metrics ────────────────────────────────────────────────────────────────
+# Flog is the primary complexity gate (see dev/quality.loki flog_check) —
+# these RuboCop thresholds catch only egregious outliers without duplicating
+# flog's more precise per-method scoring.
+
+Metrics/MethodLength:
+  Max: 35
+  CountAsOne:
+    - heredoc
+    - array
+    - hash
+  Exclude:
+    - 'test/**/*'
+    - 'bin/**/*'
+
+Metrics/AbcSize:
+  Max: 40
+  Exclude:
+    - 'test/**/*'
+    - 'bin/**/*'
+
+Metrics/ClassLength:
+  Max: 650
+  Exclude:
+    - 'test/**/*'
+    - 'bin/**/*'
+
+Metrics/ModuleLength:
+  Max: 200
+  Exclude:
+    - 'test/**/*'
+    - 'bin/**/*'
+
+Metrics/CyclomaticComplexity:
+  Max: 20
+  Exclude:
+    - 'test/**/*'
+    - 'bin/**/*'
+
+Metrics/PerceivedComplexity:
+  Max: 20
+  Exclude:
+    - 'test/**/*'
+    - 'bin/**/*'
+
+Metrics/ParameterLists:
+  Enabled: false
+
+Metrics/BlockLength:
+  # Thor's no_commands wraps a whole group of helper methods in one block
+  AllowedMethods:
+    - no_commands
+  Exclude:
+    - 'Rakefile'
+    - '*.gemspec'
+    - 'test/**/*'
+    - 'bin/**/*'

data/Archspec.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+# TrakFlow's architecture: a layered gem with pure domain models at the
+# bottom, storage and graph services in the middle, and two independent
+# interface layers (Thor CLI and MCP server) on top.
+#
+#   support (id_generator, time_parser)   <- leaf utilities
+#   config                                <- leaf, used by everything
+#   models                                <- pure domain objects
+#   storage                               <- Sequel/JSONL persistence
+#   graph                                 <- analysis over an injected db
+#   cli | mcp                             <- interfaces, unaware of each other
+
+source "lib/**/*.rb"
+
+component :support, in: %w[lib/trak_flow/id_generator.rb lib/trak_flow/time_parser.rb]
+component :config,  in: %w[lib/trak_flow/config.rb lib/trak_flow/config/**/*.rb]
+component :models,  in: "lib/trak_flow/models/**/*.rb"
+component :storage, in: "lib/trak_flow/storage/**/*.rb"
+component :graph,   in: "lib/trak_flow/graph/**/*.rb"
+component :cli,     in: %w[lib/trak_flow/cli.rb lib/trak_flow/cli/**/*.rb]
+component :mcp,     in: %w[lib/trak_flow/mcp.rb lib/trak_flow/mcp/**/*.rb]
+
+# Leaf utilities depend on nothing above them.
+support.cannot_use :config, :models, :storage, :graph, :cli, :mcp
+config.cannot_use :support, :models, :storage, :graph, :cli, :mcp
+
+# Models are pure domain objects: attributes, validation, lifecycle. They
+# must never reach into persistence or the interface layers.
+models.cannot_use :storage, :graph, :cli, :mcp
+
+# Storage maps rows to models. It must not know about the analysis layer
+# or the interfaces built on top of it.
+storage.cannot_use :graph, :cli, :mcp
+
+# Graph analyses task data through the db handle it is given — it may read
+# model constants, but must not construct storage or serve an interface.
+graph.cannot_use :storage, :cli, :mcp
+
+# CLI and MCP are peer interfaces over the same core. Neither may depend
+# on the other, so either can be extracted or dropped independently.
+cli.cannot_use :mcp
+mcp.cannot_use :cli
+
+no_cycles among: %i[support config models storage graph cli mcp]

data/CHANGELOG.md

@@ -5,7 +5,58 @@ All notable changes to TrakFlow will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## Unreleased
+## [0.2.0] - 2026-09-08
+
+### Added
+
+- Real `Archspec.rb` (replacing the `architecture :rails` placeholder)
+  encoding the gem's layering: leaf `support`/`config`, pure `models`,
+  `storage` above models, `graph` over an injected db handle, and `cli`/
+  `mcp` as peer interfaces that must not depend on each other. Enforced
+  by the `archspec_check` quality gate.
+
+### Changed
+
+- The MCP HTTP transport is now Rack-server-agnostic. `Mcp::Server` no
+  longer hard-codes Puma: `start_http` boots the transport through the
+  generic `Rackup::Handler` interface, using (in priority order) the new
+  `handler:` argument, the new `mcp.handler` config setting
+  (`TF_MCP__HANDLER`), or Rackup's default lookup — which picks whatever
+  Rack server the bundle already carries. Any server that supports
+  `rack.hijack` works (Puma, Falcon, WEBrick, iodine).
+- `Mcp::Server#rack_app` is now public API: applications that already run
+  their own Rack server can mount the MCP transport into it (e.g.
+  `map("/mcp") { run TrakFlow::Mcp::Server.new.rack_app }` in config.ru)
+  instead of letting TrakFlow start a second server.
+- The CLI `output` helpers now `yield` instead of capturing the block and
+  calling it, avoiding a proc allocation on every command's output
+  (Fasterer's block-vs-yield finding, applied across all 7 command
+  classes). Its remaining suggestions are declined in `.fasterer.yml`
+  with reasons: the while-loop rewrite trades readability for nothing in
+  IO-bound code, and the fetch-with-block form conflicts with RuboCop's
+  Style/RedundantFetchBlock for literal defaults.
+- Docs: corrected stale filenames (`issues.jsonl` → `tasks.jsonl`,
+  `config.json` → `config.yml`), MCP endpoint paths (`/mcp/sse`,
+  `/mcp/messages`), default port (3333), and environment variable names
+  (`TF_MCP__PORT`).
+
+### Fixed
+
+- `examples/cli_demo.sh` aborted before its final section: it referenced
+  the pre-rename `.trak_flow/issues.jsonl` filename.
+
+## [0.1.4] - 2026-09-08
+
+### Changed
+
+- `puma` and `rackup` are no longer gemspec dependencies. The MCP HTTP
+  transport lazy-loads them and raises a clear error with instructions
+  when they're missing; the stdio transport and the models/storage API
+  never needed them. Consumers that run the HTTP transport must add
+  `gem 'puma', '>= 7.2.1'` and `gem 'rackup'` to their own Gemfile.
+  This keeps a web server (and its CVE surface — CVE-2026-47736 /
+  CVE-2026-47737 affected puma ~> 6.0) out of consumers that only use
+  TrakFlow as a task database.
 
 ## [0.1.3] - 2026-01-03
 

data/Gemfile

@@ -6,3 +6,15 @@ gemspec
 
 gem 'ruby_llm'
 gem 'ruby_llm-mcp'
+
+group :development, :test do
+  # Optional HTTP-transport gems for the MCP server — kept out of the
+  # gemspec on purpose (consumers opt in); needed here so bin/tf_mcp's
+  # HTTP mode works during development.
+  gem 'puma', '>= 7.2.1'
+  gem 'rackup'
+
+  # Quality-gate tools invoked via `bundle exec` by the asgard quality task.
+  gem 'fasterer'
+  gem 'reek'
+end