feat: populate custom fields from Backstage entity annotations (#14)

* feat: populate service custom fields from Backstage entity annotations

Add support for passing arbitrary attributes and custom catalog properties
to Rootly services, functionalities, teams, and catalog entities from
Backstage entity annotations at sync time.

Two new annotation prefixes per entity type:
- `rootly.com/service-attr-<api_attribute>` passes through to service API
  attributes (color, notify_emails, slack_channels, etc.)
- `rootly.com/service-property-<slug_or_id>` maps to catalog properties
  array on the service

Value coercion: "true"/"false" → boolean, JSON arrays/objects parsed,
everything else stays a string.

Hardcoded fields (name, backstage_id, pagerduty_id) always win over
passthrough — annotations cannot override control-plane attributes.

Ref: PRF-2548

* docs: add annotation pass-through and custom properties to README

* fix: prevent properties injection via service-attr- prefix

Move `properties` into hardcoded override section of all 4 methods
that support it (service import/update, catalog entity import/update).
Previously, `rootly.com/service-attr-properties` could bypass the
structured property annotation path because the conditional spread
sat between passthrough and hardcoded fields.

Now `properties` always overrides passthrough, matching the same
protection as name/backstage_id/pagerduty_id.

Add 2 safety tests documenting the override contract.

Author: kwent

README.md

@@ -114,6 +114,57 @@ rootly.com/catalog-slug: customer-tier # Alternative to catalog-id. The catalog
 rootly.com/catalog-description: Customer pricing tiers # Optional. Description for the catalog when auto-creating.
 ```
 
+#### Attribute pass-through annotations
+
+You can set any Rootly API attribute on services, functionalities, teams, and catalog entities using the `attr` prefix:
+
+```yaml
+rootly.com/service-attr-<api_attribute>: "value"
+rootly.com/functionality-attr-<api_attribute>: "value"
+rootly.com/team-attr-<api_attribute>: "value"
+rootly.com/catalog-entity-attr-<api_attribute>: "value"
+```
+
+Value coercion rules:
+- `"true"` / `"false"` → boolean
+- Values starting with `[` or `{` → parsed as JSON (arrays, objects)
+- Everything else → plain string
+
+Example:
+
+```yaml
+annotations:
+  rootly.com/service-slug: my-service
+  rootly.com/service-auto-import: enabled
+  rootly.com/service-attr-color: "#FF5733"
+  rootly.com/service-attr-notify_emails: '["oncall@company.com","team@company.com"]'
+  rootly.com/service-attr-slack_channels: '[{"id":"C01ABC123","name":"oncall-channel"}]'
+  rootly.com/service-attr-show_uptime: "true"
+  rootly.com/service-attr-github_repository_name: "myorg/my-service"
+```
+
+Hardcoded fields (`name`, `description`, `backstage_id`, `pagerduty_id`, `owner_group_ids`) always take precedence and cannot be overridden via pass-through annotations.
+
+#### Custom catalog property annotations
+
+You can populate custom catalog properties (metadata fields) on services and catalog entities:
+
+```yaml
+rootly.com/service-property-<slug_or_id>: "value"
+rootly.com/catalog-entity-property-<slug_or_id>: "value"
+```
+
+The key after the prefix is the catalog property slug or UUID. The value is passed as-is to the Rootly API.
+
+Example:
+
+```yaml
+annotations:
+  rootly.com/service-slug: my-service
+  rootly.com/service-property-impact-level: "critical"
+  rootly.com/service-property-slack-channel: '{"id":"C01FE4P7458","name":"service-channel"}'
+```
+
 #### Example
 
 ```yaml

src/api.test.ts

@@ -0,0 +1,187 @@
+import { extractPassthroughAttributes, extractProperties } from './api';
+
+describe('extractPassthroughAttributes', () => {
+  const prefix = 'rootly.com/service-attr-';
+
+  it('returns empty object when annotations is undefined', () => {
+    expect(extractPassthroughAttributes(undefined, prefix)).toEqual({});
+  });
+
+  it('returns empty object when no annotations match prefix', () => {
+    const annotations = {
+      'rootly.com/service-id': '123',
+      'pagerduty.com/service-id': 'PD123',
+    };
+    expect(extractPassthroughAttributes(annotations, prefix)).toEqual({});
+  });
+
+  it('passes through simple string values', () => {
+    const annotations = {
+      'rootly.com/service-attr-color': '#FF5733',
+      'rootly.com/service-attr-github_repository_name': 'rootlyhq/my-service',
+    };
+    expect(extractPassthroughAttributes(annotations, prefix)).toEqual({
+      color: '#FF5733',
+      github_repository_name: 'rootlyhq/my-service',
+    });
+  });
+
+  it('coerces "true" and "false" to booleans', () => {
+    const annotations = {
+      'rootly.com/service-attr-show_uptime': 'true',
+      'rootly.com/service-attr-alert_broadcast_enabled': 'false',
+    };
+    expect(extractPassthroughAttributes(annotations, prefix)).toEqual({
+      show_uptime: true,
+      alert_broadcast_enabled: false,
+    });
+  });
+
+  it('parses JSON arrays', () => {
+    const annotations = {
+      'rootly.com/service-attr-notify_emails': '["alice@co.com","bob@co.com"]',
+    };
+    expect(extractPassthroughAttributes(annotations, prefix)).toEqual({
+      notify_emails: ['alice@co.com', 'bob@co.com'],
+    });
+  });
+
+  it('parses JSON objects', () => {
+    const annotations = {
+      'rootly.com/service-attr-slack_channels': '[{"id":"C01ABC","name":"oncall"}]',
+    };
+    expect(extractPassthroughAttributes(annotations, prefix)).toEqual({
+      slack_channels: [{ id: 'C01ABC', name: 'oncall' }],
+    });
+  });
+
+  it('falls back to string on invalid JSON', () => {
+    const annotations = {
+      'rootly.com/service-attr-bad_json': '{not valid json',
+    };
+    expect(extractPassthroughAttributes(annotations, prefix)).toEqual({
+      bad_json: '{not valid json',
+    });
+  });
+
+  it('ignores empty attribute name after prefix', () => {
+    const annotations = {
+      'rootly.com/service-attr-': 'value',
+    };
+    expect(extractPassthroughAttributes(annotations, prefix)).toEqual({});
+  });
+
+  it('handles mixed matching and non-matching annotations', () => {
+    const annotations = {
+      'rootly.com/service-id': '123',
+      'rootly.com/service-attr-color': '#000',
+      'rootly.com/functionality-attr-color': '#FFF',
+      'rootly.com/service-attr-show_uptime': 'true',
+    };
+    expect(extractPassthroughAttributes(annotations, prefix)).toEqual({
+      color: '#000',
+      show_uptime: true,
+    });
+  });
+
+  it('works with different prefixes', () => {
+    const annotations = {
+      'rootly.com/team-attr-color': 'blue',
+    };
+    expect(extractPassthroughAttributes(annotations, 'rootly.com/team-attr-')).toEqual({
+      color: 'blue',
+    });
+  });
+});
+
+describe('extractProperties', () => {
+  const prefix = 'rootly.com/service-property-';
+
+  it('returns empty array when annotations is undefined', () => {
+    expect(extractProperties(undefined, prefix)).toEqual([]);
+  });
+
+  it('returns empty array when no annotations match prefix', () => {
+    const annotations = {
+      'rootly.com/service-id': '123',
+    };
+    expect(extractProperties(annotations, prefix)).toEqual([]);
+  });
+
+  it('extracts properties with slug keys', () => {
+    const annotations = {
+      'rootly.com/service-property-my-custom-field': 'hello',
+    };
+    expect(extractProperties(annotations, prefix)).toEqual([
+      { catalog_property_id: 'my-custom-field', value: 'hello' },
+    ]);
+  });
+
+  it('extracts properties with UUID keys', () => {
+    const annotations = {
+      'rootly.com/service-property-dcece7f7-b73c-4f32-8b09-695abad42e60': 'world',
+    };
+    expect(extractProperties(annotations, prefix)).toEqual([
+      { catalog_property_id: 'dcece7f7-b73c-4f32-8b09-695abad42e60', value: 'world' },
+    ]);
+  });
+
+  it('keeps value as raw string (no coercion)', () => {
+    const annotations = {
+      'rootly.com/service-property-slack-channel': '{"id":"C01FE4P7458","name":"oncall"}',
+    };
+    expect(extractProperties(annotations, prefix)).toEqual([
+      { catalog_property_id: 'slack-channel', value: '{"id":"C01FE4P7458","name":"oncall"}' },
+    ]);
+  });
+
+  it('extracts multiple properties', () => {
+    const annotations = {
+      'rootly.com/service-property-field-a': 'val1',
+      'rootly.com/service-property-field-b': 'val2',
+    };
+    const result = extractProperties(annotations, prefix);
+    expect(result).toHaveLength(2);
+    expect(result).toContainEqual({ catalog_property_id: 'field-a', value: 'val1' });
+    expect(result).toContainEqual({ catalog_property_id: 'field-b', value: 'val2' });
+  });
+
+  it('ignores empty property id after prefix', () => {
+    const annotations = {
+      'rootly.com/service-property-': 'value',
+    };
+    expect(extractProperties(annotations, prefix)).toEqual([]);
+  });
+});
+
+describe('passthrough override safety', () => {
+  const attrPrefix = 'rootly.com/service-attr-';
+
+  it('hardcoded fields are not present in passthrough when same key used', () => {
+    const annotations = {
+      'rootly.com/service-attr-name': 'injected-name',
+      'rootly.com/service-attr-backstage_id': 'injected-id',
+      'rootly.com/service-attr-color': '#FF0000',
+    };
+    const result = extractPassthroughAttributes(annotations, attrPrefix);
+    expect(result).toEqual({
+      name: 'injected-name',
+      backstage_id: 'injected-id',
+      color: '#FF0000',
+    });
+    // These keys ARE extracted — the protection is that hardcoded fields
+    // override them when spread into the payload (spread order matters).
+    // This test documents that extraction itself does not filter reserved keys.
+  });
+
+  it('properties key in passthrough attrs does not bypass structured properties', () => {
+    const annotations = {
+      'rootly.com/service-attr-properties': '[{"catalog_property_id":"x","value":"injected"}]',
+    };
+    const passthroughAttrs = extractPassthroughAttributes(annotations, attrPrefix);
+    expect(passthroughAttrs.properties).toBeDefined();
+    // The payload construction puts `properties` in the hardcoded section AFTER
+    // the spread, so this injected value gets overridden. This test documents
+    // that the extraction function does return it — the safety is in spread order.
+  });
+});