picatz / picatz/flowstate

Design: where a run runs. `flow run` ergonomics across local and server, explicit and inferred, for first contact and for production

Open
#371 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

cli design enhancement kind/design-record
Dominant language
Go
Stars
9
Forks
0
Avg merge
3h 3m
Merged PRs (30d)
509

Description

Terminal-session review, owner direction. Local execution is a first-class capability of this system — not a degraded rehearsal mode — and the drivers agree by invariant, which is exactly what makes the question of where a run runs worth designing rather than defaulting into.

What today's shape does

flow run <file> means the server, always. flow run local <file> is a subcommand. Two consequences show up in one terminal session:

  • First contact fails. With nothing else set up, flow run examples/hello-world/workflow.yaml dies with dial tcp [::1]:9233: connection refused (sad-path rendering is #370) — even though the binary in hand contains a complete engine that could have run the file. The user's intent was "run this workflow"; the CLI heard "reach a server."
  • The grammar bends around it: USAGE: flow run [command] [workflow-file] — a usage line where a positional and a subcommand compete for the same slot, which reads as a symptom of local being bolted on rather than designed in.

The tension to hold

Both of these are true, and a design has to serve both:

  • The goal is often a server. Durable execution is the product; a team running production wants every run on Temporal, and wants a typo'd environment to fail loudly rather than silently execute on a laptop. Some deployments will want local execution unavailable — a run that happened outside the audited control plane is a policy violation, not a convenience.
  • Local is intentional, not a fallback of last resort. It is the authoring loop, the CI rehearsal, the embedded/edge story, and for some users the whole product. It should feel designed-for, not like the server's understudy.

The space to explore (not a conclusion)

  1. Explicitness with configuration, not guessing. A flow run that silently falls back to local when the dial fails is the worst point in the space: a network blip turns a production deploy into a laptop run. If "run however I'm configured" exists, it should be a configured mode — e.g. a profile/context (FLOWSTATE_ADDRESS set → server; an explicit driver: local in a context → local; neither → a crisp error that teaches both commands, per #370). The resolution should be printed at run start ("running locally" / "running on

    as ") so there is never a run whose venue was a surprise. Fail-closed thinking applies: ambiguity is an error with a great message, not a guess.

  2. Symmetry of grammar. If local is first-class, the spelling should say so: flow run --local <file> vs subcommand vs flow run local as today, and whichever is chosen, watching/inputs/outputs/exit codes behave identically (they largely do already — that invariant is the asset this design spends).

  3. The deny direction. A deployment that must not allow local runs needs a way to say so that the binary respects (policy in the trust/config surface, not an honor-system flag). Conversely a laptop that must not accidentally reach production wants the same mechanism pointed the other way.

  4. Teaching moments. flow init's NEXT block, the unreachable-server hint (#370), and the help examples should all tell one coherent story about the two venues, in the same order, so a new user forms the right model in the first five minutes and a veteran can set a context once and stop thinking about it.

Related: #370 (the sad path when the server is missing), #295 (local rehearsal fidelity — what "the same" must mean), docs/CLI_DESIGN.md (the charter this has to land inside).

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the current flow run and flow run local grammar described in the issue, then read docs/CLI_DESIGN.md and the related discussions in #370 and #295. Done means an agreed design covering explicit venue selection, symmetric behavior, deny policies, and coherent teaching in flow init and help examples.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
cli, developer-experience, documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.