bd-sink

Name: bd-sink
Author: Lonsdale201

21stars1forks

How to install bd-sink?

lonsdale201/wp-agent-skills/bd-sink

$npx -y skills add Lonsdale201/wp-agent-skills --skill bd-sink

Installs into the current project.

Summary

Add a new sink to better-data — code that writes

Files · 1

View on GitHub

SKILL.md

1	# better-data: Adding a sink
2
3	For library maintainers integrating WRITE-side support for a new WordPress data store with better-data — comment meta, attachments, custom taxonomies, plugin-specific tables. The shape is set by `PostSink` and `OptionSink`; deviating breaks the `HasWpSinks` trait API and surprises consumers who've internalized the dual projection-vs-convenience model.
4
5	## Misconception this skill corrects
6
7	> "I'll write the values directly to `update_post_meta` — slashing is the caller's problem."
8
9	Wrong direction. WordPress's write pipeline calls `wp_unslash()` on inbound data on the way to the DB. If you pass a raw value through `update_post_meta($id, $key, 'a"b')` without slashing first, WP unslashes a string with no slashes and stores `'ab'` (the `"` survives, but escaped/quoted values get mangled). Convenience methods (`insert`, `update`, `save`) MUST `wp_slash()` before calling any WP write function. Verified in [src/Sink/PostSink.php:144](PostSink.php) (`$args = \wp_slash($args);`), [PostSink.php:183](PostSink.php) (`\wp_update_post(\wp_slash($args), true)`), [PostSink.php:191](PostSink.php) (`\update_post_meta($postId, $key, \wp_slash($value))`).
10
11	The mirror trap on the projection side: `toArgs`/`toMeta` MUST return raw values, NOT pre-slashed. Callers that take projections and pass them to their OWN WP write calls (`wp_insert_post`) would double-slash and corrupt every backslash on round-trip.
12
13	So: convenience slashes, projection does not. The two paths share `SinkProjection::prepareValue` ([src/Internal/SinkProjection.php:193](SinkProjection.php)) which handles type-shaping, encryption, and DataObject unwrapping but never slashes.
14
15	Other AI-prone misconceptions:
16
17	- "Asymmetric write/read is fine — encrypt on write, store as plain on read." Wrong. Every asymmetric encryption bug in Phase-8.7's OptionSink came from this pattern. If you encrypt, the matching source MUST decrypt.
18	- "Storing a `DataObject` instance with `update_post_meta($id, 'thing', $dto)` — WP will serialize it." Technically true, but stores a class name in the DB; on class rename or removal you have unrecoverable garbage. Always project through `SinkProjection::prepareValue` which recurses arrays and turns nested `DataObject`s into plain arrays.
19	- "I'll do my own slashing inside `prepareValue`." Wrong layer — projection stays raw. Slashing is the boundary concern at the WP-call site.
20
21	## When to use this skill
22
23	Trigger when ANY of the following is true:
24
25	- Creating a new file under `src/Sink/`.
26	- Adding `toArgs` / `toMeta` / `insert` / `update` / `save` methods on a sink class.
27	- Adding a `saveAsX` shortcut to `HasWpSinks`.
28	- Reviewing a PR that calls `update__meta` / `wp_insert_` directly without `wp_slash()`.
29	- Reviewing a PR that adds at-rest encryption to one sink without verifying the matching source decrypts.
30
31	## Workflow
32
33	### 1. File location
34
35	Sinks live in `src/Sink/`. The pure projection logic (no WP calls) lives in `src/Internal/SinkProjection.php` — DON'T duplicate it. Your sink delegates type shaping there and adds the WP-specific calls.
36
37	### 2. The two-mode contract
38
39	Every sink ships TWO modes that share one projection:
40
41	Projection mode (caller drives the write):
42
43	```php
44	public static function toArgs(
45	DataObject $dto,
46	?array $only = null,
47	bool $strict = false,
48	bool $skipNullDeletes = false,
49	): array;
50
51	/**
52	* @return array{write: array<string, mixed>, delete: list<string>}
53	*/
54	public static function toMeta(
55	DataObject $dto,
56	?array $only = null,
57	bool $strict = false,
58	bool $skipNullDeletes = false,
59	): array;
60	```
61
62	`toArgs` returns the array shape `wp_insert_<thing>` / `wp_update_<thing>` accepts. `toMeta` returns `['write

People who liked this also viewed

6 picks

Type

find-skillsHelps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skSkillsJul 20262.6M27k
grill-meA relentless interview to sharpen a plan or design.SkillsJul 2026633k182k
vercel-react-best-practicesVercel's official collection of agent skillsSkillsJul 2026573k29k
improve-codebase-architectureScan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.SkillsJul 2026522k182k
setup-matt-pocock-skillsConfigure this repo for the engineering skills — set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills.SkillsJul 2026454k182k
triageMove issues and external PRs through a state machine of triage roles — categorise, verify, grill if needed, and write agent-ready briefs.SkillsJul 2026424k182k

bd-sink

21stars1forks

View on GitHub

How to install bd-sink?

lonsdale201/wp-agent-skills/bd-sink

$npx -y skills add Lonsdale201/wp-agent-skills --skill bd-sink

Installs into the current project.

Summary

Add a new sink to better-data — code that writes

Files · 1

View on GitHub

SKILL.md

1	# better-data: Adding a sink
2
3	For library maintainers integrating WRITE-side support for a new WordPress data store with better-data — comment meta, attachments, custom taxonomies, plugin-specific tables. The shape is set by `PostSink` and `OptionSink`; deviating breaks the `HasWpSinks` trait API and surprises consumers who've internalized the dual projection-vs-convenience model.
4
5	## Misconception this skill corrects
6
7	> "I'll write the values directly to `update_post_meta` — slashing is the caller's problem."
8
9	Wrong direction. WordPress's write pipeline calls `wp_unslash()` on inbound data on the way to the DB. If you pass a raw value through `update_post_meta($id, $key, 'a"b')` without slashing first, WP unslashes a string with no slashes and stores `'ab'` (the `"` survives, but escaped/quoted values get mangled). Convenience methods (`insert`, `update`, `save`) MUST `wp_slash()` before calling any WP write function. Verified in [src/Sink/PostSink.php:144](PostSink.php) (`$args = \wp_slash($args);`), [PostSink.php:183](PostSink.php) (`\wp_update_post(\wp_slash($args), true)`), [PostSink.php:191](PostSink.php) (`\update_post_meta($postId, $key, \wp_slash($value))`).
10
11	The mirror trap on the projection side: `toArgs`/`toMeta` MUST return raw values, NOT pre-slashed. Callers that take projections and pass them to their OWN WP write calls (`wp_insert_post`) would double-slash and corrupt every backslash on round-trip.
12
13	So: convenience slashes, projection does not. The two paths share `SinkProjection::prepareValue` ([src/Internal/SinkProjection.php:193](SinkProjection.php)) which handles type-shaping, encryption, and DataObject unwrapping but never slashes.
14
15	Other AI-prone misconceptions:
16
17	- "Asymmetric write/read is fine — encrypt on write, store as plain on read." Wrong. Every asymmetric encryption bug in Phase-8.7's OptionSink came from this pattern. If you encrypt, the matching source MUST decrypt.
18	- "Storing a `DataObject` instance with `update_post_meta($id, 'thing', $dto)` — WP will serialize it." Technically true, but stores a class name in the DB; on class rename or removal you have unrecoverable garbage. Always project through `SinkProjection::prepareValue` which recurses arrays and turns nested `DataObject`s into plain arrays.
19	- "I'll do my own slashing inside `prepareValue`." Wrong layer — projection stays raw. Slashing is the boundary concern at the WP-call site.
20
21	## When to use this skill
22
23	Trigger when ANY of the following is true:
24
25	- Creating a new file under `src/Sink/`.
26	- Adding `toArgs` / `toMeta` / `insert` / `update` / `save` methods on a sink class.
27	- Adding a `saveAsX` shortcut to `HasWpSinks`.
28	- Reviewing a PR that calls `update__meta` / `wp_insert_` directly without `wp_slash()`.
29	- Reviewing a PR that adds at-rest encryption to one sink without verifying the matching source decrypts.
30
31	## Workflow
32
33	### 1. File location
34
35	Sinks live in `src/Sink/`. The pure projection logic (no WP calls) lives in `src/Internal/SinkProjection.php` — DON'T duplicate it. Your sink delegates type shaping there and adds the WP-specific calls.
36
37	### 2. The two-mode contract
38
39	Every sink ships TWO modes that share one projection:
40
41	Projection mode (caller drives the write):
42
43	```php
44	public static function toArgs(
45	DataObject $dto,
46	?array $only = null,
47	bool $strict = false,
48	bool $skipNullDeletes = false,
49	): array;
50
51	/**
52	* @return array{write: array<string, mixed>, delete: list<string>}
53	*/
54	public static function toMeta(
55	DataObject $dto,
56	?array $only = null,
57	bool $strict = false,
58	bool $skipNullDeletes = false,
59	): array;
60	```
61
62	`toArgs` returns the array shape `wp_insert_<thing>` / `wp_update_<thing>` accepts. `toMeta` returns `['write

People who liked this also viewed

6 picks

Type