feat(platform): support multiple policy rules per plugin (#1182)

* feat(platform): support multiple policy rules per plugin

Extend the command policy framework from single-Rule to multi-Rule
semantics. A plugin (or policy.yml) may now contribute several scoped
Rules; the engine combines them with OR -- a command is allowed when it
satisfies every axis of at least one rule. This lets one integration
apply different risk ceilings and identity restrictions to different
command groups.

The cross-plugin fail-closed boundary is preserved: two distinct plugins
both calling Restrict still aborts startup (multiple_restrict_plugins).
Single-Rule behaviour is fully backward compatible -- the rejection
reason_code / rule_name / envelope shape are byte-for-byte unchanged;
multi-rule rejection surfaces the aggregate reason_code no_matching_rule.

- engine: New keeps single-rule compat, add NewSet for OR over rules
- resolver: dedupe by owner (one plugin may contribute many rules),
  return []*Rule; yaml gains a top-level rules: list
- registrar/builder/staging: Restrict may be called more than once;
  retire the double_restrict error
- config policy show / config plugins show: emit a rules array
- inventory: PluginEntry.Rules is now a slice (fixes last-rule-wins
  overwrite when a plugin contributes multiple rules)

* fix(platform): clone rules in Builder.Restrict and inventory snapshot

Address review feedback. Builder.Restrict stored the caller's *Rule
directly, so reusing and mutating one Rule object across multiple
Restrict calls collapsed entries to the last mutation; clone the rule and
its slices on append, mirroring the staging registrar.

BuildInventory likewise reused the source Allow/Deny/Identities slices;
copy them when building the RuleView snapshot instead of relying on
cloneInventory downstream.

Add a regression test: reusing and mutating one Rule across two Restrict
calls now yields two independent rules.

* fix(platform): skip yaml when a plugin owns policy; reject empty rules list

Two policy-config robustness fixes from review:

- A malformed ~/.lark-cli/policy.yml could abort a plugin-governed
  binary. applyUserPolicyPruning read yaml before resolving, and
  build.go fail-closes on any policy error when a plugin is present.
  Plugin rules shadow yaml anyway, so skip reading yaml entirely when a
  plugin contributed rules -- an unrelated broken file on the user's
  machine can no longer lock the CLI.

- A present-but-empty "rules: []" collapsed to a single all-zero Rule
  that allows every annotated command ("looks like policy, enforces
  almost nothing"). yaml.Parse now distinguishes absent from
  present-but-empty (Rules is a pointer) and rejects the empty list.

Add regression tests for both.

cmd/config/plugins.go

@@ -82,8 +82,8 @@ func runConfigPluginsShow(f *cmdutil.Factory) error {
 			"version":      p.Version,
 			"capabilities": p.Capabilities,
 		}
-		if p.Rule != nil {
-			entry["rule"] = p.Rule
+		if len(p.Rules) > 0 {
+			entry["rules"] = p.Rules
 		}
 		entry["hooks"] = map[string]any{
 			"observers": p.Observers,

cmd/config/policy.go

@@ -59,16 +59,20 @@ func runConfigPolicyShow(f *cmdutil.Factory) error {
 		"source_name":  sourceName,
 		"denied_paths": active.DeniedPaths,
 	}
-	if active.Rule != nil {
-		out["rule"] = map[string]any{
-			"name":              active.Rule.Name,
-			"description":       active.Rule.Description,
-			"allow":             active.Rule.Allow,
-			"deny":              active.Rule.Deny,
-			"max_risk":          active.Rule.MaxRisk,
-			"identities":        active.Rule.Identities,
-			"allow_unannotated": active.Rule.AllowUnannotated,
+	if len(active.Rules) > 0 {
+		rules := make([]map[string]any, 0, len(active.Rules))
+		for _, r := range active.Rules {
+			rules = append(rules, map[string]any{
+				"name":              r.Name,
+				"description":       r.Description,
+				"allow":             r.Allow,
+				"deny":              r.Deny,
+				"max_risk":          r.MaxRisk,
+				"identities":        r.Identities,
+				"allow_unannotated": r.AllowUnannotated,
+			})
 		}
+		out["rules"] = rules
 	}
 	output.PrintJson(f.IOStreams.Out, out)
 	return nil

cmd/config/policy_test.go

@@ -57,7 +57,7 @@ func TestConfigPolicyShow_PluginActive(t *testing.T) {
 		MaxRisk: "read",
 	}
 	cmdpolicy.SetActive(&cmdpolicy.ActivePolicy{
-		Rule: rule,
+		Rules: []*platform.Rule{rule},
 		Source: cmdpolicy.ResolveSource{
 			Kind: cmdpolicy.SourcePlugin,
 			Name: "secaudit",
@@ -83,12 +83,16 @@ func TestConfigPolicyShow_PluginActive(t *testing.T) {
 	if got["denied_paths"] != float64(42) {
 		t.Errorf("denied_paths = %v, want 42", got["denied_paths"])
 	}
-	ruleMap, ok := got["rule"].(map[string]any)
+	rulesAny, ok := got["rules"].([]any)
+	if !ok || len(rulesAny) != 1 {
+		t.Fatalf("rules field missing or wrong shape: %v", got["rules"])
+	}
+	ruleMap, ok := rulesAny[0].(map[string]any)
 	if !ok {
-		t.Fatalf("rule field missing or wrong type")
+		t.Fatalf("rules[0] wrong type")
 	}
 	if ruleMap["name"] != "secaudit" {
-		t.Errorf("rule.name = %v", ruleMap["name"])
+		t.Errorf("rules[0].name = %v", ruleMap["name"])
 	}
 }
 
@@ -101,7 +105,7 @@ func TestConfigPolicyShow_YamlSourceNameIsEmpty(t *testing.T) {
 	t.Cleanup(cmdpolicy.ResetActiveForTesting)
 
 	cmdpolicy.SetActive(&cmdpolicy.ActivePolicy{
-		Rule: &platform.Rule{Name: "my-yaml-rule"},
+		Rules: []*platform.Rule{{Name: "my-yaml-rule"}},
 		Source: cmdpolicy.ResolveSource{
 			Kind: cmdpolicy.SourceYAML,
 			Name: "/Users/alice/.lark-cli/policy.yml",

cmd/platform_bootstrap.go

@@ -36,47 +36,71 @@ const userPolicyFileName = "policy.yml"
 // pluginRules carries Plugin.Restrict() contributions collected from
 // the InstallAll phase; nil/empty is fine.
 func applyUserPolicyPruning(rootCmd *cobra.Command, pluginRules []cmdpolicy.PluginRule) error {
-	yamlPath, err := userPolicyPath()
-	if err != nil {
-		// No user home dir means we cannot locate the policy. Treat
-		// the same as "file missing": no pruning, no error. This keeps
-		// non-interactive CI environments (no HOME set) running.
-		yamlPath = ""
+	// Plugin rules shadow the yaml source entirely (Resolve: plugin >
+	// yaml). When a plugin contributed rules we therefore do NOT even
+	// read ~/.lark-cli/policy.yml: build.go fail-CLOSES on any policy
+	// error once a plugin is present, so reading a malformed yaml here
+	// would let an unrelated broken file on the user's machine abort a
+	// plugin-governed binary -- exactly the file the plugin is supposed
+	// to shadow. Skipping the read keeps the shadow contract honest.
+	var (
+		yamlRules []*platform.Rule
+		yamlPath  string
+	)
+	if len(pluginRules) == 0 {
+		p, perr := userPolicyPath()
+		if perr != nil {
+			// No user home dir means we cannot locate the policy. Treat
+			// the same as "file missing": no pruning, no error. This keeps
+			// non-interactive CI environments (no HOME set) running.
+			p = ""
+		}
+		yamlPath = p
+		loaded, lerr := cmdpolicy.LoadYAMLPolicy(yamlPath)
+		if lerr != nil {
+			// Yaml-only failures are fail-OPEN at the caller (warn and
+			// continue), but the active-policy snapshot is process-global
+			// and may still carry data from a previous build in long-lived
+			// embedders / tests. Clear it explicitly so `config policy
+			// show` reports "no policy" instead of a stale rule that
+			// doesn't reflect the current command tree.
+			cmdpolicy.SetActive(nil)
+			return lerr
+		}
+		yamlRules = loaded
 	}
 
-	yamlRule, err := cmdpolicy.LoadYAMLPolicy(yamlPath)
-	if err != nil {
-		// Yaml-only failures are fail-OPEN at the caller (warn and
-		// continue), but the active-policy snapshot is process-global
-		// and may still carry data from a previous build in long-lived
-		// embedders / tests. Clear it explicitly so `config policy
-		// show` reports "no policy" instead of a stale rule that
-		// doesn't reflect the current command tree.
-		cmdpolicy.SetActive(nil)
-		return err
-	}
-
-	rule, source, err := cmdpolicy.Resolve(cmdpolicy.Sources{
+	rules, source, err := cmdpolicy.Resolve(cmdpolicy.Sources{
 		PluginRules: pluginRules,
-		YAMLRule:    yamlRule,
+		YAMLRules:   yamlRules,
 		YAMLPath:    yamlPath,
 	})
 	if err != nil {
 		cmdpolicy.SetActive(nil)
 		return err
 	}
-	if rule == nil {
+	if len(rules) == 0 {
 		cmdpolicy.SetActive(&cmdpolicy.ActivePolicy{Source: source})
 		return nil
 	}
 
-	engine := cmdpolicy.New(rule)
+	// RuleName attributes a denial to a specific rule in the envelope.
+	// With a single rule that is unambiguous and preserves the legacy
+	// envelope verbatim; with several rules a denial means "no rule
+	// granted it", which has no single owner, so the field is left empty
+	// and reason_code=no_matching_rule carries the meaning instead.
+	ruleName := ""
+	if len(rules) == 1 {
+		ruleName = rules[0].Name
+	}
+
+	engine := cmdpolicy.NewSet(rules)
 	decisions := engine.EvaluateAll(rootCmd)
-	denied := cmdpolicy.BuildDeniedByPath(rootCmd, decisions, source, rule.Name)
+	denied := cmdpolicy.BuildDeniedByPath(rootCmd, decisions, source, ruleName)
 	cmdpolicy.Apply(rootCmd, denied)
 
 	cmdpolicy.SetActive(&cmdpolicy.ActivePolicy{
-		Rule:        rule,
+		Rules:       rules,
 		Source:      source,
 		DeniedPaths: len(denied),
 	})

cmd/platform_bootstrap_test.go

@@ -13,6 +13,8 @@ import (
 
 	"github.com/spf13/cobra"
 
+	"github.com/larksuite/cli/extension/platform"
+	"github.com/larksuite/cli/internal/cmdpolicy"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/output"
 )
@@ -184,6 +186,39 @@ func TestApplyUserPolicyPruning_malformedYamlReturnsError(t *testing.T) {
 	}
 }
 
+// When a plugin contributed rules, a malformed user policy.yml must NOT
+// abort: plugin rules shadow yaml entirely, so the broken file is never
+// read. Regression -- previously LoadYAMLPolicy ran first and an
+// unrelated broken yaml on the user's machine could fatal a
+// plugin-governed binary (build.go fail-CLOSES on policy errors when a
+// plugin is present).
+func TestApplyUserPolicyPruning_pluginRulesSkipBrokenYaml(t *testing.T) {
+	cfgDir := tmpHome(t)
+	t.Cleanup(cmdpolicy.ResetActiveForTesting)
+	writePolicy(t, cfgDir, "::: not yaml :::") // broken on purpose
+
+	pluginRules := []cmdpolicy.PluginRule{
+		{PluginName: "secaudit", Rule: &platform.Rule{
+			Name:    "docs-only",
+			Allow:   []string{"docs/**"},
+			MaxRisk: "write",
+		}},
+	}
+	root := fakeTree(t)
+	if err := applyUserPolicyPruning(root, pluginRules); err != nil {
+		t.Fatalf("plugin rules must shadow (and skip reading) yaml; broken yaml should not error, got %v", err)
+	}
+
+	// Plugin rule actually applied: im/+send is outside docs/** -> hidden.
+	if send := findLeaf(t, root, "im", "+send"); !send.Hidden {
+		t.Errorf("im/+send should be hidden by plugin rule (not in docs/** allow)")
+	}
+	// docs/+update is within allow and at/below max_risk -> stays visible.
+	if update := findLeaf(t, root, "docs", "+update"); update.Hidden {
+		t.Errorf("docs/+update should remain visible under plugin rule")
+	}
+}
+
 // Semantically-invalid Rule (bad MaxRisk) reaches ValidateRule inside
 // Resolve and produces an error. This is the safety contract: a typo in
 // the rule must not silently lower the pruning bar.