feat(event): compile the catalog and harden the consume pipeline

.gitleaks.toml

@@ -3,6 +3,18 @@ title = "lark-cli gitleaks config"
 [extend]
 useDefault = true
 
+# Extends the default rule of the same id: the base regex is kept and this
+# allowlist is appended to that rule only, leaving every other rule untouched.
+[[rules]]
+id = "generic-api-key"
+
+[[rules.allowlists]]
+description = "EventKey identifiers (dotted lowercase names like minutes.minute.generated_v1) in the event catalog fixtures are public catalog data, not credentials; the entropy heuristic misreads them"
+condition = "AND"
+paths = ['''cmd/event/testdata/golden/.*''']
+regexTarget = "secret"
+regexes = ['''^[a-z0-9_]+(\.[a-z0-9_]+){2,}$''']
+
 [[rules]]
 id = "lark-bot-app-id"
 description = "Detect Lark bot app ids"

cmd/build.go

@@ -20,7 +20,6 @@ import (
 	"github.com/larksuite/cli/cmd/skill"
 	cmdupdate "github.com/larksuite/cli/cmd/update"
 	"github.com/larksuite/cli/cmd/whoami"
-	_ "github.com/larksuite/cli/events"
 	"github.com/larksuite/cli/internal/affordance"
 	"github.com/larksuite/cli/internal/apicatalog"
 	"github.com/larksuite/cli/internal/build"

cmd/event/blocked_decision_test.go

@@ -0,0 +1,200 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package event
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"testing"
+
+	"github.com/larksuite/cli/cmd/event/render"
+	"github.com/larksuite/cli/errs"
+	appconsume "github.com/larksuite/cli/internal/event/application/consume"
+	"github.com/larksuite/cli/internal/event/catalog"
+)
+
+const blockedTestKey = "im.message.receive_v1"
+
+// blockingPreflight reports one blocked precondition, the shape a real
+// preflight produces when credentials cannot be used.
+type blockingPreflight struct {
+	name     string
+	blockErr error
+}
+
+func (p *blockingPreflight) Read(context.Context, *catalog.Entry, string) ([]appconsume.Precondition, error) {
+	return []appconsume.Precondition{
+		{Name: "console_event_published", Status: appconsume.PreconditionOK},
+		{
+			Name:     p.name,
+			Status:   appconsume.PreconditionBlocked,
+			Detail:   p.blockErr.Error(),
+			BlockErr: p.blockErr,
+		},
+	}, nil
+}
+
+type fixedIdentity string
+
+func (i fixedIdentity) Resolve(context.Context, *catalog.Entry) (string, error) {
+	return string(i), nil
+}
+
+// spyRunner records whether the delivery stream was ever started.
+type spyRunner struct{ started bool }
+
+func (r *spyRunner) Run(context.Context, appconsume.PrepareFunc) error {
+	r.started = true
+	return nil
+}
+
+func blockedDecisionFixture(t *testing.T) (*catalog.Entry, *appconsume.Service, *appconsume.Decision, error, error) {
+	t.Helper()
+	snap := compileCatalog()
+	entry, ok := snap.Resolve(blockedTestKey)
+	if !ok {
+		t.Fatalf("catalog has no %s", blockedTestKey)
+	}
+	blockErr := errs.NewPermissionError(errs.SubtypeMissingScope,
+		"missing scopes for %s", blockedTestKey).
+		WithMissingScopes("im:message", "im:chat:readonly").
+		WithHint("run `lark-cli auth login --scope im:message` and retry")
+
+	svc := &appconsume.Service{
+		Strategies: appconsume.DefaultRegistry(),
+		Identity:   fixedIdentity("bot"),
+		Preflight:  &blockingPreflight{name: "credentials_available", blockErr: blockErr},
+	}
+	decision, err := svc.Decide(context.Background(), entry, appconsume.Request{EventKey: blockedTestKey}, appconsume.ExecutionContext{})
+	return entry, svc, decision, blockErr, err
+}
+
+// The dry-run envelope for a blocked decision is a contract an orchestrator
+// reads: ok stays true and the exit code stays 0, because the preview itself
+// succeeded, and "would this run" is answered inside the payload. Anything that
+// only checks ok or the exit code would treat a refusal as a green light, so
+// the status and the blocked precondition must be present and named.
+func TestBlockedDecision_DryRunEnvelopeStatesTheRefusal(t *testing.T) {
+	_, _, decision, _, err := blockedDecisionFixture(t)
+	if err != nil {
+		t.Fatalf("deciding must succeed even when a precondition blocks, got: %v", err)
+	}
+
+	var stdout, stderr bytes.Buffer
+	if err := render.WriteDecisionJSON(&stdout, &stderr, "bot", decision.View()); err != nil {
+		t.Fatalf("render: %v", err)
+	}
+
+	var envelope struct {
+		OK     bool `json:"ok"`
+		DryRun bool `json:"dry_run"`
+		Data   struct {
+			Decision struct {
+				Status        string `json:"status"`
+				Preconditions []struct {
+					Name          string   `json:"name"`
+					Status        string   `json:"status"`
+					Detail        string   `json:"detail"`
+					Subtype       string   `json:"subtype"`
+					Hint          string   `json:"hint"`
+					MissingScopes []string `json:"missing_scopes"`
+				} `json:"preconditions"`
+				WouldWrite []string `json:"would_write"`
+			} `json:"decision"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal(stdout.Bytes(), &envelope); err != nil {
+		t.Fatalf("stdout is not a decision envelope: %v\n%s", err, stdout.String())
+	}
+
+	if !envelope.OK || !envelope.DryRun {
+		t.Errorf("the preview succeeded, so ok and dry_run stay true; got: %s", stdout.String())
+	}
+	if envelope.Data.Decision.Status != "blocked" {
+		t.Errorf("status = %q, want \"blocked\": this is the only field that tells a caller the real run would refuse",
+			envelope.Data.Decision.Status)
+	}
+
+	var blocked *struct {
+		Name          string   `json:"name"`
+		Status        string   `json:"status"`
+		Detail        string   `json:"detail"`
+		Subtype       string   `json:"subtype"`
+		Hint          string   `json:"hint"`
+		MissingScopes []string `json:"missing_scopes"`
+	}
+	for i := range envelope.Data.Decision.Preconditions {
+		if envelope.Data.Decision.Preconditions[i].Status == "blocked" {
+			blocked = &envelope.Data.Decision.Preconditions[i]
+		}
+	}
+	if blocked == nil {
+		t.Fatalf("a blocked decision must name the precondition that blocks it, got: %s", stdout.String())
+	}
+	if blocked.Name != "credentials_available" {
+		t.Errorf("blocked precondition = %q, want the one the preflight reported", blocked.Name)
+	}
+	if blocked.Detail == "" {
+		t.Error("a blocked precondition must carry a detail; without it the caller knows only that something failed")
+	}
+	// The preview is read before acting, so it has to say what to do about the
+	// refusal — the same recovery information a real run puts in its error
+	// envelope, in the same machine-readable shape.
+	if blocked.Subtype != string(errs.SubtypeMissingScope) {
+		t.Errorf("subtype = %q, want the classification callers branch on", blocked.Subtype)
+	}
+	if blocked.Hint == "" {
+		t.Error("a blocked precondition must carry the recovery hint; the preview is the surface an agent reads before acting")
+	}
+	if len(blocked.MissingScopes) != 2 {
+		t.Errorf("missing_scopes = %v, want the concrete scopes to grant", blocked.MissingScopes)
+	}
+	// A precondition that passed has nothing to recover from and must stay bare.
+	for _, pc := range envelope.Data.Decision.Preconditions {
+		if pc.Status == "ok" && (pc.Subtype != "" || pc.Hint != "" || len(pc.MissingScopes) > 0) {
+			t.Errorf("a passing precondition must carry no recovery fields, got %+v", pc)
+		}
+	}
+	// Declared write side effects stay declarations in a preview.
+	if len(envelope.Data.Decision.WouldWrite) == 0 {
+		t.Error("the preview must still declare what a real run would write")
+	}
+}
+
+// Executing a blocked decision returns the preflight's own error and never
+// starts the stream. Everything the command sets up for a live run — the stdin
+// EOF watcher included — hangs off the runner for this reason: started earlier,
+// it announced "stdin closed — shutting down" on a run that was actually
+// refused for an unmet precondition.
+func TestBlockedDecision_ExecuteNeverStartsTheStream(t *testing.T) {
+	entry, svc, decision, blockErr, err := blockedDecisionFixture(t)
+	if err != nil {
+		t.Fatalf("decide: %v", err)
+	}
+
+	runner := &spyRunner{}
+	execErr := svc.Execute(context.Background(), entry, decision, runner, appconsume.ExecutionContext{})
+
+	if runner.started {
+		t.Error("a blocked decision must not start the delivery stream")
+	}
+	problem, ok := errs.ProblemOf(execErr)
+	if !ok {
+		t.Fatalf("executing a blocked decision must return the preflight's typed error, got: %v", execErr)
+	}
+	if problem.Subtype != errs.SubtypeMissingScope {
+		t.Errorf("subtype = %q, want the preflight's own subtype preserved", problem.Subtype)
+	}
+	// The caller must receive the preflight's own error, not a copy of its
+	// message: the hint is what tells an operator how to recover, and a rewrap
+	// would drop it.
+	if !errors.Is(execErr, blockErr) {
+		t.Errorf("execute returned %v, want the preflight's own error", execErr)
+	}
+	if problem.Hint == "" {
+		t.Error("the recovery hint the preflight attached must survive to the caller")
+	}
+}

cmd/event/bus.go

@@ -16,12 +16,14 @@
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/event"
+	"github.com/larksuite/cli/internal/event/adapter/lark/websocket"
+	"github.com/larksuite/cli/internal/event/adapter/localbus/transport"
 	"github.com/larksuite/cli/internal/event/bus"
-	"github.com/larksuite/cli/internal/event/transport"
+	"github.com/larksuite/cli/internal/event/catalog"
 )
 
 // NewCmdBus creates the hidden `event _bus` daemon subcommand, forked by the consume client; fork argv lives in consume/startup.go.
-func NewCmdBus(f *cmdutil.Factory) *cobra.Command {
+func NewCmdBus(f *cmdutil.Factory, snap *catalog.Snapshot) *cobra.Command {
 	var domain string
 
 	cmd := &cobra.Command{
@@ -44,7 +46,13 @@
 			}
 
 			tr := transport.New()
-			b := bus.NewBus(cfg.AppID, cfg.AppSecret, domain, tr, logger)
+			ingress := &websocket.FeishuSource{
+				AppID:     cfg.AppID,
+				AppSecret: cfg.AppSecret,
+				Domain:    domain,
+				Logger:    logger,
+			}
+			b := bus.NewBus(cfg.AppID, cfg.AppSecret, domain, tr, logger, snap, ingress)
 
 			ctx, cancel := context.WithCancel(cmd.Context())
 			defer cancel()

cmd/event/bus_test.go

@@ -27,7 +27,7 @@ func TestBusCommandLoggerSetupFailureIsTypedFileIO(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
 		AppID: "cli_bus_test", AppSecret: "secret", Brand: core.BrandFeishu,
 	})
-	cmd := NewCmdBus(f)
+	cmd := NewCmdBus(f, compileCatalog())
 	cmd.SetArgs([]string{})
 
 	err := cmd.Execute()