feat(cli): add the --config launch option #87

Merged

natsukium merged 3 commits from feat/config-path-flag-27 into main 2026-09-04 21:29:17 +09:00

Conversation 0 Commits 3 Files changed 23 +866 -163

natsukium commented 2026-09-04 21:16:22 +09:00

Owner

Copy link

Fixes #27.

A one-off launch could not name its own config.toml. This adds one
root flag, felis --config PATH, that reaches window launches (the
resolved absolute path is forwarded to the frontend, which watches it
for live reloads too), the config path|check|show-effective verbs,
and doctor. A relative path is resolved in the front door and only
there, because the window it launches runs elsewhere and cannot
recover what the user meant.

felis-client-core now distinguishes a selected config from the
default one: a file missing at the default location stays the
first-run "use the defaults" case, while a selection that is not
there is a missing_file error. The verbs that read no config file
refuse the flag at exit 2 rather than ignoring it, the same way they
already refuse the carrier globals. There is no environment-variable
spelling: felis stamps the spawning environment into every session, so
one set for a launch would redirect the felis config runs inside
that window too.

Doc cascade: docs/reference/cli.md (global options, the config
verb exit codes, the frontend exec contract),
docs/reference/config.md (discovery, the missing_file diagnostic,
the absent/unreadable-file table),
docs/explanation/architecture/control-surfaces.md (why one flag and
no env var), docs/reference/control-surfaces.md,
docs/reference/testing.md, docs/backlog.md, CHANGELOG.md, and
the product-shipped skills/felis/SKILL.md.

Rebased onto current main; the stacked parent (#23) is already in
main, and the felis version verb that landed meanwhile was folded
into the no-config verb list, its refusal test, and the docs.

Verified: just check green (fmt, clippy, nextest, deny); reviewed by
plan/correctness/docs lenses and pi sol

Deferred

• describe_config_source helper plus the "selected by --config"
  phrasing in doctor's config row and config path's human output —
  no acceptance criterion needs the wording; the selected absolute
  path is already reported by every consumer.
• Making an explicitly selected but unusable config a hard startup
  failure for the GUI client (it currently warns and falls back to
  defaults, as load always has) — no criterion covers GUI startup
  behavior, and changing it would alter the stay-alive-on-a-typo
  contract.
• An end-to-end test that a launched window actually reads the
  forwarded file — needs a real winit/wgpu session; the forwarding is
  pinned at the argv level by
  a_relative_config_selection_is_forwarded_absolute instead.
• The single source-description helper the plan required was not
  implemented — already on the implementer's deferred list with the
  same reasoning: no acceptance criterion requires the wording, and
  the selected absolute path is already reported by every consumer.
• sessions/notifications --help still advertises short_id
  fields the JSON no longer emits — traces to commit 5da5427d
  ("Refs #23"), stacked below issue #27's commits but not part of
  them; out of scope for the --config flag acceptance criteria.
• A landing that reaches the pool before the fan-out is recorded is
  dropped, leaving the target pending forever — traces to commit
  5b2f709e, an unrelated switch/queued-landing feature stacked below
  issue #27's commits; not part of this issue's scope.
• CLI --help text still advertises short_id fields removed from
  these replies — duplicate of the short_id finding; traces to
  commit 5da5427d ("Refs #23"), out of scope for issue #27.
• CHANGELOG entry still describes a felis ssh alias this same branch
  removes — traces to commits 5da5427d/f1509a33 ("Refs #23"), stacked
  below issue #27's commits; not part of the --config flag work this
  round is reviewing.
• Nothing tests that felis-client accepts or honors --config; only
  the sender side of the exec contract is pinned — no acceptance
  criterion names a required GUI-side unit test by number, and the
  implementer's own deferred list already excludes the stronger
  end-to-end version of this same gap as needing a real winit/wgpu
  session; a lighter parse-level test is the same class of extra
  hardening, not a demonstrated wrong output.

Fixes #27. A one-off launch could not name its own `config.toml`. This adds one root flag, `felis --config PATH`, that reaches window launches (the resolved absolute path is forwarded to the frontend, which watches it for live reloads too), the `config path|check|show-effective` verbs, and `doctor`. A relative path is resolved in the front door and only there, because the window it launches runs elsewhere and cannot recover what the user meant. `felis-client-core` now distinguishes a selected config from the default one: a file missing at the default location stays the first-run "use the defaults" case, while a selection that is not there is a `missing_file` error. The verbs that read no config file refuse the flag at exit `2` rather than ignoring it, the same way they already refuse the carrier globals. There is no environment-variable spelling: felis stamps the spawning environment into every session, so one set for a launch would redirect the `felis config` runs inside that window too. Doc cascade: `docs/reference/cli.md` (global options, the `config` verb exit codes, the frontend exec contract), `docs/reference/config.md` (discovery, the `missing_file` diagnostic, the absent/unreadable-file table), `docs/explanation/architecture/control-surfaces.md` (why one flag and no env var), `docs/reference/control-surfaces.md`, `docs/reference/testing.md`, `docs/backlog.md`, `CHANGELOG.md`, and the product-shipped `skills/felis/SKILL.md`. Rebased onto current `main`; the stacked parent (#23) is already in `main`, and the `felis version` verb that landed meanwhile was folded into the no-config verb list, its refusal test, and the docs. Verified: just check green (fmt, clippy, nextest, deny); reviewed by plan/correctness/docs lenses and pi sol ## Deferred - `describe_config_source` helper plus the "selected by --config" phrasing in doctor's config row and `config path`'s human output — no acceptance criterion needs the wording; the selected absolute path is already reported by every consumer. - Making an explicitly selected but unusable config a hard startup failure for the GUI client (it currently warns and falls back to defaults, as `load` always has) — no criterion covers GUI startup behavior, and changing it would alter the stay-alive-on-a-typo contract. - An end-to-end test that a launched window actually reads the forwarded file — needs a real winit/wgpu session; the forwarding is pinned at the argv level by `a_relative_config_selection_is_forwarded_absolute` instead. - The single source-description helper the plan required was not implemented — already on the implementer's deferred list with the same reasoning: no acceptance criterion requires the wording, and the selected absolute path is already reported by every consumer. - `sessions`/`notifications` `--help` still advertises `short_id` fields the JSON no longer emits — traces to commit 5da5427d ("Refs #23"), stacked below issue #27's commits but not part of them; out of scope for the `--config` flag acceptance criteria. - A landing that reaches the pool before the fan-out is recorded is dropped, leaving the target pending forever — traces to commit 5b2f709e, an unrelated switch/queued-landing feature stacked below issue #27's commits; not part of this issue's scope. - CLI `--help` text still advertises `short_id` fields removed from these replies — duplicate of the `short_id` finding; traces to commit 5da5427d ("Refs #23"), out of scope for issue #27. - CHANGELOG entry still describes a `felis ssh` alias this same branch removes — traces to commits 5da5427d/f1509a33 ("Refs #23"), stacked below issue #27's commits; not part of the `--config` flag work this round is reviewing. - Nothing tests that `felis-client` accepts or honors `--config`; only the sender side of the exec contract is pinned — no acceptance criterion names a required GUI-side unit test by number, and the implementer's own deferred list already excludes the stronger end-to-end version of this same gap as needing a real winit/wgpu session; a lighter parse-level test is the same class of extra hardening, not a demonstrated wrong output.

natsukium added 3 commits 2026-09-04 21:16:22 +09:00

feat(client-core): distinguish a selected config from the default ... d9daef1cf3

`--config PATH` needs a loader that can tell "the file the user named"
from "the file platform discovery guessed at": an absent file is a
first run in the second case and a typo in the first, and answering a
question about a named document with the defaults would report facts
about a different one. `ConfigSource` carries that distinction to
every front door, so the CLI verbs, `doctor`, and the GUI client
cannot disagree about which file they read or about what its absence
means.

Refs #27

feat(cli): add the --config launch option ... f2083767d5

A one-off launch could not name its own config.toml, so trying a
setting meant editing the real profile and putting it back; the
Windows config and doctor suites were `cfg(unix)` for the same
missing surface, because the known-folder API that resolves
`%APPDATA%` reads no environment variable and a temp profile is
therefore unreachable from a test.

One root flag serves both. It reaches window launches (forwarded to
the frontend, which also watches the selected file for live reloads),
the `config` verbs, and `doctor`; the verbs that read no config file
refuse it rather than ignoring it, as they already refuse the carrier
globals. A relative path is resolved here and only here, because the
window it launches runs elsewhere and cannot recover what the user
meant. An environment variable was the alternative and is rejected:
felis stamps the spawning environment into every session, so one set
for a launch would redirect the `felis config` runs inside that
window too.

The config and doctor suites now select their fixture with the flag
and run on Windows; what stays Unix-only is the discovery test and
the unreadable-file case, which need the known folder and mode bits.

Refs #27

docs: record the one --config control surface ... 84f26c4706

The decision needs a home before the flag can be relied on: the
explanation twin now carries why one per-invocation flag was chosen
and why an environment variable and a config key naming another
config were rejected, with the revisit trigger for a multi-profile
workflow. The reference pages state the resulting rules — resolution,
the per-verb acceptance, and the missing-selection error — and the
Windows coverage gap closes in testing.md and the backlog because the
suites that were blocked on this decision now run there.

Refs #27

natsukium merged commit 84f26c4706 into main 2026-09-04 21:29:17 +09:00

natsukium deleted branch feat/config-path-flag-27 2026-09-04 21:29:17 +09:00

natsukium referenced this pull request 2026-09-08 01:39:59 +09:00

[v0.1/CLI Args Review] CLI 引数のリリース前設計レビュー #55

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels   

priority/P0

Must be resolved before the v0.1.0 tag

  

priority/P1

Must be settled before the first public contract freezes

  

priority/P2

Explicitly deferred until after v0.1.0

  

release/v0.1.0

Work tracked for the first tagged release

  

status/blocked

Cannot start now: waits on an upstream release, another issue, or a recorded revisit trigger

  

status/planned

Triaged with a source-grounded plan and a passed pi review; ready to implement

  

type/bug

Shipped behavior that contradicts the docs or the code's own intent; needs a product code change

  

type/design

An open scope or trade-off question; needs a recorded decision in the owning explanation doc before code

  

type/test-gap

Documented or reviewed behavior that no test pins; usually split from a review finding, needs no product code change

  

type/tracker

Parent issue that tracks child work

No labels

priority/P0

priority/P1

priority/P2

release/v0.1.0

status/blocked

status/planned

type/bug

type/design

type/test-gap

type/tracker

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

natsukium/felis!87

No description provided.