Skip to content

An extension cannot describe a command group; star mints '<name> commands' for every node above a leaf #841

Open

Description

@David-Noble-at-work

An extension declares leaf commands by dotted name — gh.issues.report — and star synthesises the
intermediate groups, gh and issues, so that star gh issues report resolves. The spec has
no way to describe a group, so star mints a placeholder:

$ star gh --help
gh commands

Available Commands:
  issues      issues commands
  labels      labels commands

The leaves are fine — star gh issues report --help carries the help the spec gave it — but every
level above a leaf reads " commands". For a service node like gh, which the tree grammar
(star-extensions.md, The Shape of the Tree) makes the first thing a person types, that is the
worst place for the help to be empty.

Minted at cmd/star/main.go:473: Short: fmt.Sprintf("%s commands", parts[i]).

Wanted

A way for the spec to describe groups. Two shapes, either is fine:

groups:
  gh: GitHub under the NobleFactor classification scheme
  gh.issues: The issue report and its audits
  gh.labels: The label set every participating repository carries

or a help on the first command that names the group, inherited upward. When two extensions
contribute to one group — config show and config sync beside the built-in config verbs —
the first description seen wins and a second differing one is a load-time warning.

Until then the placeholder should at least be honest: " — see its subcommands" reads better
than " commands", which looks like a description that was never written. It is.

Observed 2026-09-06 with com.noblefactor.ops.GitHub (noblefactor-ops#140).


Epic: #445

Activity

  1. David-Noble-at-work commented on Sep 12, 2026

    @David-Noble-at-work
    ContributorAuthor

    From #835's pull request: cli.CheckGroupsTakeNoAction is §14's invariant 7, a group takes no action, and star's root test is the one that does not call it yet, because setup is a leaf with an action that the loader then uses as a parent. When this issue lets an extension declare a group, star's root test calls the checker like the other three, and the epic's ledger row 7 closes fully.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Epic:StarlarkSurfaceThe Starlark authoring surfacetaskImplementation work item

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions