clipboard-transformer-rules

name	clipboard-transformer-rules
description	Locate, write, edit, validate, test, and organize Clipboard Transformer YAML or TOML rules. Use for clipboard rewrites, URL cleanup, regular expressions, rulesets, app/format filters, local or remote imports, trusted shell rules, WASM plugin rules, config diagnostics, effective-rule inspection, and rule-focused CLI workflows, whether or not the clipboard-transformer CLI is installed.

Clipboard Transformer Rules

Make the smallest correct config change. Preserve comments, ordering, formatting style, imports, and unrelated user settings. Prefer application-level validation, but keep discovery and editing usable without an installed CLI.

Load only the references needed for the task:

• Read references/paths.md when locating config, state, cache, schema, or plugin paths.
• Read references/rules.md before authoring shared fields, built-in text/URL rules, rulesets, or group descriptors.
• Read references/shell-rules.md before adding or changing shell or item-shell rules.
• Read references/imports.md when inspecting, adding, or changing imports.
• Read references/plugins.md for plugin-owned rule types or plugin commands.
• Read references/cli.md before constructing validation, rule-catalog, effective-view, transform, watch, or diagnostic commands.

Workflow

1. Locate the active config.

   • Use a user-supplied path when present.
   • Otherwise run clipboard-transformer paths when available.
   • In a repository checkout, prefer an existing target/release/clipboard-transformer, then use cargo run --locked -- paths when practical.
   • Without a CLI, resolve platform and XDG paths from references/paths.md and check both config.yaml and config.toml.
   • Remember that launching the desktop app creates the starter YAML and schema when neither format exists; CLI initialization is optional.
   • If neither exists, create config.yaml directly only when the user authorized a new config. Ask only when multiple existing configs remain plausible.

2. Inspect the main config and relevant imports.

   • Classify inline rules, rulesets, local imports, remote imports, shell rules, plugin rules, or a mixture.
   • Open relevant local imports. Treat remote imports as external dependencies, not casual edit targets.
   • Do not change plugin permissions or global shell authorization merely to make a proposed rule pass.

3. Select the narrowest rule shape.

   • Use groups for compact enablement of related rules across the desktop app, CLI, and future SDKs.
   • Use url-cleanup for simple HTTP(S) query-parameter removal.
   • Use url for one structural URL operation.
   • Use regexp for UTF-8 text rewrites and capture replacements.
   • Use ruleset only for grouping or ordered match policy.
   • Use shell or item-shell only when the user explicitly needs trusted native execution and the portable built-ins cannot express the behavior.
   • For namespaced plugin types, follow references/plugins.md and inspect that plugin's example, manifest, schema, or existing rules. Never guess plugin-owned fields.
   • Use clipboard-transformer rules list to discover known built-in, native, and plugin rule types. Add --available-only when current config and plugin availability should filter the catalog.

4. Edit conservatively.

   • Give every real rule a stable non-empty id; prefer lowercase kebab case.
   • Prefer single-quoted YAML strings for regexes and replacements.
   • Omit formats when [text] is correct. Otherwise preserve priority.
   • Pair non-empty apps with app_mode: blacklist or whitelist.
   • Treat patterns as Rust regexes, not PCRE. Avoid look-around, pattern backreferences, conditional groups, and overly broad prose rewrites.
   • Keep one transform per url rule; compose operations with a ruleset.

5. Validate with the strongest available method.

   • Prefer clipboard-transformer config check --config-file <path>, then pipe exact samples through clipboard-transformer transform - --config-file <path>. Add --input-format <format> when the rule does not select plain text.
   • In a checkout, use the existing release binary or the same subcommands through cargo run --locked --.
   • For import work, also inspect clipboard-transformer rules view effective --config-file <path>.
   • The explicit - selects stdin/stdout: transform - --config-file <path>. Without it, transform reads and writes the current clipboard; --preview suppresses that write.
   • Across rule-loading commands, --config-file always means a path and --config always means a self-contained inline YAML or TOML document.
   • Use config schema --output <path> only when the user asks for a separate schema artifact. Normal desktop startup maintains the schema beside the active config.
   • When no executable is available, perform structural review against the relevant references and the generated schema beside the config. State that import refresh, plugin initialization, and rule compilation were not verified.

6. Test behavior.

   • Use the rule's actual selected format instead of always choosing text.
   • Test an expected match, a no-match, and ordering for rulesets.
   • For shell rules, test exit 0, no-match exit 3, stderr diagnostics, timeout behavior when relevant, and avoid using live sensitive clipboard content.

7. Report the changed file, rule id, validation method, and observed results. Mention any unavailable app-level verification without implying the CLI had to be installed.

Editing rules

• Add a rule near related inline rules, inside a fitting existing ruleset, or in an established local import—whichever creates the least churn.
• Create a new import only when it improves an already modular or crowded config.
• Keep relative imports relative to the importing file.
• Do not edit cached URL-import files as authored source.
• Runtime parsing ignores unknown fields; generated JSON Schema is stricter. Do not treat runtime validation alone as typo detection.
• For URL cleanup, prefer exact names, then prefixes, then regex patterns.
• Never weaken SHA-256 pins or remote shell permissions to make validation pass.

References

• references/paths.md: config discovery and platform/XDG path resolution.
• references/rules.md: shared fields and built-in regexp, URL, cleanup, ruleset, and group semantics.
• references/shell-rules.md: executable rule behavior and trust boundaries.
• references/imports.md: local/remote import resolution, caching, and pins.
• references/plugins.md: plugin rule discovery and lifecycle commands.
• references/cli.md: rule-focused commands, config-source contracts, and validation scope.