Rename rowbinary-parser skill to a read+write codec; split docs and source by direction (#921)

The `@clickhouse/rowbinary` skill/package gained a writer (and now uses
the new type parser), so it's no longer a parser-only skill. This
reshapes it into a read+write **codec** and reorganizes both the source
tree and the skill docs by direction.

## What changed

- **Renamed the skill** `clickhouse-js-node-rowbinary-parser` →
`clickhouse-js-node-rowbinary` (dir, SKILL.md frontmatter, package
metadata, the two workflow files, the `release` skill, and root/skills
docs). The npm package name stays `@clickhouse/rowbinary`.
- **Split `src/` by direction**: readers → `src/readers/`, writers →
`src/writers/`, and dropped the now-redundant `_writer` suffix
(`integers_writer.ts` → `writers/integers.ts`). Subpath exports now
reflect the folders (`@clickhouse/rowbinary/readers/<type>`,
`/writers/<type>`); the root export and the new `./writer` barrel are
unchanged.
- **Split the skill doc** `SKILL.md` (which had grown large) into a lean
router plus two self-contained sides — `reader.md` and `writer.md` —
since a task normally needs only one direction. SKILL.md keeps the
format gate, the pick-your-side router, and the cross-cutting
principles; each side holds its own decisions, guidance, and per-type
reference table.
- **Tightened `writer.md` to the intended layering** `SKILL.md →
writer.md → source file with JSDoc`: each paragraph keeps the judgment
(when/why) and points at the exact `src/writers/<file>.ts`, with
mechanics living in (descriptive) JSDoc. A per-paragraph verification
pass corrected a few claims (Sink is caller-supplied state; hoisted
offsets must sync back to `sink.pos`; all date writers floor;
`DateTime64` floors on the JS ms number).

## Verification

- Typecheck clean; **724/724 tests pass**; `npm run build` emits the new
`dist/readers` / `dist/writers` layout and both barrels resolve.
- The first commit is a **pure rename** (193 files, 0 content changes)
so the relocation reviews at a glance; subsequent commits carry the
content.

## Notes / follow-ups

- Subpath imports are a **breaking change** for anyone importing
`@clickhouse/rowbinary/<type>` (now `/readers/<type>`), but this rides
along in the already-pending, unreleased `0.2.0` (npm latest is `0.1.2`)
that also introduces the whole writer surface — so **no extra version
bump**.
- Not yet done: a CHANGELOG `0.2.0` note documenting the rename + moved
subpaths.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: peter-leonov-ch

.claude/skills/release/SKILL.md

@@ -9,8 +9,8 @@ description: >
   of the packages: `@clickhouse/client` (Node.js), `@clickhouse/client-web`
   (Web), `@clickhouse/client-common` (deprecated, rarely released), the
   standalone `@clickhouse/datatype-parser` (the type parser, under
-  `packages/datatype-parser`), or `@clickhouse/rowbinary` (the RowBinary parser
-  skill/package, under `skills/clickhouse-js-node-rowbinary-parser`). The agent
+  `packages/datatype-parser`), or `@clickhouse/rowbinary` (the RowBinary codec
+  skill/package, under `skills/clickhouse-js-node-rowbinary`). The agent
   drives the GitHub Actions workflows (`gh workflow run`), watches CI, pauses at
   the human-judgment points (PR review, the approval gate, GitHub Release text),
   and hands the deployment-approval link back to the human. Do NOT use this for
@@ -32,8 +32,8 @@ This skill is the source of truth for the release process. It supersedes the old
    - `@clickhouse/client-common` — **deprecated**, effectively frozen; only cut a
      final standalone release if explicitly asked.
    - `@clickhouse/datatype-parser` — standalone type parser (`packages/datatype-parser`)
-   - `@clickhouse/rowbinary` — standalone RowBinary parser skill/package
-     (`skills/clickhouse-js-node-rowbinary-parser`)
+   - `@clickhouse/rowbinary` — standalone RowBinary codec skill/package
+     (`skills/clickhouse-js-node-rowbinary`)
 
    The flow forks into two families — **workspace client packages** (client /
    client-web / client-common) and **standalone packages** (datatype-parser /
@@ -56,7 +56,7 @@ This skill is the source of truth for the release process. It supersedes the old
 > - `@clickhouse/client-web` → `publish-client-web.yml`
 > - `@clickhouse/client-common` → `publish-client-common.yml`
 > - `@clickhouse/datatype-parser` → `publish-datatype-parser.yml`
-> - `@clickhouse/rowbinary` → `publish-skill-rowbinary-parser.yml`
+> - `@clickhouse/rowbinary` → `publish-skill-rowbinary.yml`
 >
 > Each client workflow has two triggers: an automatic `head` publish on push to
 > `release` and a manual `latest` publish via `workflow_dispatch`. The standalone
@@ -233,13 +233,13 @@ beta** for them.
 Edit the version in the package's `package.json` (these have **no** `src/version.ts`):
 
 - `@clickhouse/datatype-parser` → `packages/datatype-parser/package.json`
-- `@clickhouse/rowbinary` → `skills/clickhouse-js-node-rowbinary-parser/package.json`
+- `@clickhouse/rowbinary` → `skills/clickhouse-js-node-rowbinary/package.json`
 
 Do this in a normal PR to `main`, together with the relevant entry in **that
 package's own** `CHANGELOG.md` (verify the changelog as in Part A, Step 1):
 
 - `@clickhouse/datatype-parser` → `packages/datatype-parser/CHANGELOG.md`
-- `@clickhouse/rowbinary` → `skills/clickhouse-js-node-rowbinary-parser/CHANGELOG.md`
+- `@clickhouse/rowbinary` → `skills/clickhouse-js-node-rowbinary/CHANGELOG.md`
 
 Merge it.
 
@@ -257,8 +257,8 @@ Dispatch the package's own publish workflow from the `release` branch. These tak
 ```bash
 # type parser:
 gh workflow run publish-datatype-parser.yml --ref release
-# rowbinary parser skill/package:
-gh workflow run publish-skill-rowbinary-parser.yml --ref release
+# rowbinary codec skill/package:
+gh workflow run publish-skill-rowbinary.yml --ref release
 ```
 
 Each workflow builds, packs + smoke-tests the tarball, publishes it to `latest`
@@ -280,7 +280,7 @@ gh run watch <run-id>
 Same as Part A, Step 6, using the standalone tag (`datatype-parser-v<ver>` /
 `rowbinary-v<ver>`) and the notes from that package's own `CHANGELOG.md`
 (`packages/datatype-parser/CHANGELOG.md` or
-`skills/clickhouse-js-node-rowbinary-parser/CHANGELOG.md`). No `--title`, no
+`skills/clickhouse-js-node-rowbinary/CHANGELOG.md`). No `--title`, no
 `--prerelease`. Backfill any missing releases.
 
 ---
@@ -300,7 +300,7 @@ Same as Part A, Step 6, using the standalone tag (`datatype-parser-v<ver>` /
 
 1. Bump version in the package's `package.json` + its own `CHANGELOG.md` via a PR to `main` → merge.
 2. `gh pr create --base release --head main` → review → merge.
-3. `gh workflow run publish-datatype-parser.yml --ref release` (or `publish-skill-rowbinary-parser.yml`) → **approve**, watch.
+3. `gh workflow run publish-datatype-parser.yml --ref release` (or `publish-skill-rowbinary.yml`) → **approve**, watch.
 4. `gh release create <…-v…-tag> --notes-file <changelog-section>`; backfill.
 
 **Always:** per package · each package has its **own** `CHANGELOG.md` (root is frozen) · `release` is protected (fix via `main`) · every publish needs `npm-publish` approval · `head` betas are untracked · GitHub Release notes come from the package's `CHANGELOG.md` with no explicit `--title`.

…flows/publish-skill-rowbinary-parser.yml …ub/workflows/publish-skill-rowbinary.yml.github/workflows/publish-skill-rowbinary-parser.yml renamed to .github/workflows/publish-skill-rowbinary.yml .github/workflows/publish-skill-rowbinary-parser.yml renamed to .github/workflows/publish-skill-rowbinary.yml

@@ -1,9 +1,9 @@
-name: "publish: rowbinary parser"
+name: "publish: rowbinary"
 
 # Independent publish + release for the standalone @clickhouse/rowbinary
-# package (the RowBinary parser skill). Like the per-package client publish
+# package (the RowBinary codec skill). Like the per-package client publish
 # workflows (publish-client*.yml), it carries its own version in
-# skills/clickhouse-js-node-rowbinary-parser/package.json and ships on its own
+# skills/clickhouse-js-node-rowbinary/package.json and ships on its own
 # cadence. Triggered manually, and — like those workflows — must be dispatched from
 # the `release` branch: the npm-publish environment is protected so only that
 # branch may deploy (the repo's human-in-the-loop release gate). Dispatches from
@@ -49,7 +49,7 @@ jobs:
       id-token: write # Required for npm OIDC authentication and provenance
     defaults:
       run:
-        working-directory: skills/clickhouse-js-node-rowbinary-parser
+        working-directory: skills/clickhouse-js-node-rowbinary
     outputs:
       version: ${{ steps.version.outputs.version }}
     steps:
@@ -97,7 +97,7 @@ jobs:
           # expose their parsers, from the exact artifact we are about to publish.
           node --input-type=module -e "
             import * as rb from '@clickhouse/rowbinary';
-            import * as ints from '@clickhouse/rowbinary/integers';
+            import * as ints from '@clickhouse/rowbinary/readers/integers';
             if (typeof rb.readRows !== 'function') throw new Error('readRows missing from main export');
             if (typeof ints.readUInt8 !== 'function') throw new Error('readUInt8 missing from subpath export');
             console.log('OK: packed tarball imports cleanly');
@@ -181,7 +181,7 @@ jobs:
           # expose their parsers to a downstream consumer.
           node --input-type=module -e "
             import * as rb from '@clickhouse/rowbinary';
-            import * as ints from '@clickhouse/rowbinary/integers';
+            import * as ints from '@clickhouse/rowbinary/readers/integers';
             if (typeof rb.readRows !== 'function') throw new Error('readRows missing from main export');
             if (typeof ints.readUInt8 !== 'function') throw new Error('readUInt8 missing from subpath export');
             console.log('OK: @clickhouse/rowbinary@${PUBLISHED_VERSION} imports cleanly');

…rkflows/tests-skill-rowbinary-parser.yml …thub/workflows/tests-skill-rowbinary.yml.github/workflows/tests-skill-rowbinary-parser.yml renamed to .github/workflows/tests-skill-rowbinary.yml .github/workflows/tests-skill-rowbinary-parser.yml renamed to .github/workflows/tests-skill-rowbinary.yml

@@ -1,4 +1,4 @@
-name: "skill: rowbinary parser"
+name: "skill: rowbinary"
 
 permissions: {}
 on:
@@ -7,15 +7,15 @@ on:
     branches:
       - main
     paths:
-      - .github/workflows/tests-skill-rowbinary-parser.yml
-      - skills/clickhouse-js-node-rowbinary-parser/**
+      - .github/workflows/tests-skill-rowbinary.yml
+      - skills/clickhouse-js-node-rowbinary/**
       # The skill depends on @clickhouse/datatype-parser; rerun against local
       # parser changes so a parser regression cannot pass this suite unnoticed.
       - packages/datatype-parser/**
   pull_request:
     paths:
-      - .github/workflows/tests-skill-rowbinary-parser.yml
-      - skills/clickhouse-js-node-rowbinary-parser/**
+      - .github/workflows/tests-skill-rowbinary.yml
+      - skills/clickhouse-js-node-rowbinary/**
       - packages/datatype-parser/**
 
 concurrency:
@@ -36,7 +36,7 @@ jobs:
     runs-on: ubuntu-latest
     defaults:
       run:
-        working-directory: skills/clickhouse-js-node-rowbinary-parser
+        working-directory: skills/clickhouse-js-node-rowbinary
     steps:
       - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
 
@@ -69,7 +69,7 @@ jobs:
     runs-on: ubuntu-latest
     defaults:
       run:
-        working-directory: skills/clickhouse-js-node-rowbinary-parser
+        working-directory: skills/clickhouse-js-node-rowbinary
     strategy:
       fail-fast: false
       matrix:

AGENTS.md

@@ -7,7 +7,7 @@ This root file holds repo-wide guidance. Folder-specific guidance lives in neste
 - [`packages/AGENTS.md`](packages/AGENTS.md) — client source packages: log-message conventions, package structure, and intentional node/web duplication.
 - [`examples/AGENTS.md`](examples/AGENTS.md) — the example corpus layout and conventions.
 - [`skills/AGENTS.md`](skills/AGENTS.md) — shipped agent skills and how they are declared.
-  - [`skills/clickhouse-js-node-rowbinary-parser/AGENTS.md`](skills/clickhouse-js-node-rowbinary-parser/AGENTS.md) — `@clickhouse/rowbinary` reader/writer conventions (tests, no defensive validation).
+  - [`skills/clickhouse-js-node-rowbinary/AGENTS.md`](skills/clickhouse-js-node-rowbinary/AGENTS.md) — `@clickhouse/rowbinary` reader/writer conventions (tests, no defensive validation).
 - [`docs/AGENTS.md`](docs/AGENTS.md) — embedded troubleshooting / how-to pages.
 - [`tests/clickhouse-test-runner/AGENTS.md`](tests/clickhouse-test-runner/AGENTS.md) — the upstream SQL test harness and allowlist strategy.
 
@@ -34,7 +34,7 @@ For every pull request review, make sure to provide an evaluation of the followi
    - `@clickhouse/client-web` → [`packages/client-web/CHANGELOG.md`](packages/client-web/CHANGELOG.md)
    - `@clickhouse/client-common` (deprecated) → [`packages/client-common/CHANGELOG.md`](packages/client-common/CHANGELOG.md)
    - `@clickhouse/datatype-parser` → [`packages/datatype-parser/CHANGELOG.md`](packages/datatype-parser/CHANGELOG.md)
-   - `@clickhouse/rowbinary` → [`skills/clickhouse-js-node-rowbinary-parser/CHANGELOG.md`](skills/clickhouse-js-node-rowbinary-parser/CHANGELOG.md)
+   - `@clickhouse/rowbinary` → [`skills/clickhouse-js-node-rowbinary/CHANGELOG.md`](skills/clickhouse-js-node-rowbinary/CHANGELOG.md)
 
    A change to shared code that is bundled into both clients (the common module) affects **both** `@clickhouse/client` and `@clickhouse/client-web`, so update both of their changelogs. Follow the existing format exactly:
    - Entries go under the **top-most version heading** of that package's changelog. If the most recent `# x.y.z` heading corresponds to an **already-released** version (check `git tag`), open a **new** top-level `# x.y.z` heading that matches the unreleased version in that package's `package.json`; otherwise append to the existing top heading.

README.md

@@ -118,7 +118,7 @@ Each package keeps its own changelog:
 - `@clickhouse/client-web` — [`packages/client-web/CHANGELOG.md`](./packages/client-web/CHANGELOG.md)
 - `@clickhouse/client-common` (deprecated) — [`packages/client-common/CHANGELOG.md`](./packages/client-common/CHANGELOG.md)
 - `@clickhouse/datatype-parser` — [`packages/datatype-parser/CHANGELOG.md`](./packages/datatype-parser/CHANGELOG.md)
-- `@clickhouse/rowbinary` — [`skills/clickhouse-js-node-rowbinary-parser/CHANGELOG.md`](./skills/clickhouse-js-node-rowbinary-parser/CHANGELOG.md)
+- `@clickhouse/rowbinary` — [`skills/clickhouse-js-node-rowbinary/CHANGELOG.md`](./skills/clickhouse-js-node-rowbinary/CHANGELOG.md)
 
 History through `@clickhouse/client` 1.23.0 lives in the now-frozen repository-wide [`CHANGELOG.md`](./CHANGELOG.md).
 

packages/client-node/package.json

@@ -35,14 +35,14 @@
         "path": "./skills/clickhouse-js-node-troubleshooting"
       },
       {
-        "name": "clickhouse-js-node-rowbinary-parser",
-        "path": "./skills/clickhouse-js-node-rowbinary-parser"
+        "name": "clickhouse-js-node-rowbinary",
+        "path": "./skills/clickhouse-js-node-rowbinary"
       }
     ]
   },
   "scripts": {
     "pack": "npm pack",
-    "prepack": "rm -rf skills && cp ../../README.md ../../LICENSE . && cp -r ../../skills . && RBP=skills/clickhouse-js-node-rowbinary-parser && rm -rf $RBP/tests $RBP/node_modules $RBP/dist $RBP/package.json $RBP/package-lock.json $RBP/tsconfig.json $RBP/tsconfig.build.json $RBP/vitest.config.ts $RBP/.gitignore $RBP/LICENSE $RBP/eval_result*.md",
+    "prepack": "rm -rf skills && cp ../../README.md ../../LICENSE . && cp -r ../../skills . && RBP=skills/clickhouse-js-node-rowbinary && rm -rf $RBP/tests $RBP/node_modules $RBP/dist $RBP/package.json $RBP/package-lock.json $RBP/tsconfig.json $RBP/tsconfig.build.json $RBP/vitest.config.ts $RBP/.gitignore $RBP/LICENSE $RBP/eval_result*.md",
     "typecheck": "tsc --noEmit",
     "lint": "eslint --max-warnings=0 .",
     "lint:fix": "eslint . --fix",

skills/AGENTS.md

@@ -1,6 +1,6 @@
 # Recommendations for AI agents — `skills/`
 
-Guidance for the shipped agent skills. See the [repo-root `AGENTS.md`](../AGENTS.md) for cross-cutting guidance. The `@clickhouse/rowbinary` skill has its own [`clickhouse-js-node-rowbinary-parser/AGENTS.md`](clickhouse-js-node-rowbinary-parser/AGENTS.md).
+Guidance for the shipped agent skills. See the [repo-root `AGENTS.md`](../AGENTS.md) for cross-cutting guidance. The `@clickhouse/rowbinary` skill has its own [`clickhouse-js-node-rowbinary/AGENTS.md`](clickhouse-js-node-rowbinary/AGENTS.md).
 
 - Each shipped skill must also be listed in the `agents.skills` array of
   [`packages/client-node/package.json`](../packages/client-node/package.json) so downstream tooling can

…ouse-js-node-rowbinary-parser/.gitignore …/clickhouse-js-node-rowbinary/.gitignoreskills/clickhouse-js-node-rowbinary-parser/.gitignore renamed to skills/clickhouse-js-node-rowbinary/.gitignore skills/clickhouse-js-node-rowbinary-parser/.gitignore renamed to skills/clickhouse-js-node-rowbinary/.gitignore

@@ -1,6 +1,6 @@
 # Recommendations for AI agents — `@clickhouse/rowbinary`
 
-Guidance for the [`clickhouse-js-node-rowbinary-parser`](.) package (the RowBinary parser library and agent skill). See the [repo-root `AGENTS.md`](../../AGENTS.md) for cross-cutting guidance.
+Guidance for the [`clickhouse-js-node-rowbinary`](.) package (the RowBinary codec library and agent skill). See the [repo-root `AGENTS.md`](../../AGENTS.md) for cross-cutting guidance.
 
 This package has a symmetric reader/writer codebase.