From ec3be0516ddaffc715d875df8deb1300fc58d72a Mon Sep 17 00:00:00 2001 From: dKosarevsky <36589322+dKosarevsky@users.noreply.github.com> Date: Thu, 8 Oct 2026 17:09:05 -0700 Subject: [PATCH] chore: prepare 0.1.1 documentation and tooling release --- CHANGELOG.md | 20 ++++++++++++++++++++ docs/RELEASING.md | 4 ++-- docs/USAGE.md | 2 +- package-lock.json | 4 ++-- package.json | 3 ++- scripts/test-package.mjs | 1 + test/docs.test.mjs | 13 ++++++++++++- 7 files changed, 40 insertions(+), 7 deletions(-) create mode 100644 CHANGELOG.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..bd30d9c --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,20 @@ +# Changelog + +Version headings describe repository changes. Check [npm](https://www.npmjs.com/package/@agent-axiom/streamsplit) for published versions. + +## 0.1.1 + +Documentation, examples, and release-tooling update. The public API, parser harness implementation, Node >=20 requirement, and zero-runtime-dependency contract are unchanged. + +- Correct the npm installation instructions and use a development dependency by default. +- Clarify that integration examples and demo commands require a source checkout. +- Document and test three real parser integrations: eventsource-parser, ndjson, and @streamparser/json. The JSON adapter and its dependency are development-only. +- Add runnable integration recipes, including the real SSE adapter's broken-decoder failure and exact fixed replay. +- Prepare an opt-in OIDC publication workflow with protected-environment and source/archive verification. Enabling publishing access remains a separate maintainer action. +- Include this changelog in the package archive. + +See [integration recipes](docs/INTEGRATIONS.md) and [release preparation](docs/RELEASING.md). + +## 0.1.0 + +Initial public package with byte-oriented chunk-invariance assertions, deterministic schedules, bounded failure reduction, exact fixture replay, ESM exports, and TypeScript declarations. diff --git a/docs/RELEASING.md b/docs/RELEASING.md index 55c9f42..5bf7c4d 100644 --- a/docs/RELEASING.md +++ b/docs/RELEASING.md @@ -45,9 +45,9 @@ Official requirements rechecked **2026-10-08**: - npm publisher setup needs package write access and account 2FA. The package must exist. `npm trust` setup commands require npm >=11.15.0; publishing itself requires npm >=11.5.1 and Node >=22.14. - Approve persistent publishing access for `@agent-axiom/streamsplit` from GitHub owner `agent-axiom`, repository `streamsplit`, workflow filename `publish.yml`, environment `npm`. The filename is case-sensitive and excludes `.github/workflows/`. - This workflow uses direct `npm publish`, which must be explicitly allowed. New publishers otherwise default to staging; granting stage-only access will not enable this workflow. Dist-tag management is not needed. -- Before enabling, approve/configure the GitHub `npm` environment with required reviewers, prevent self-review, and restrict deployment tags. Protect release tags and `main` as appropriate. A YAML environment name alone does not establish these protections. +- Before enabling, approve/configure the GitHub `npm` environment with required reviewers and restricted deployment tags. Enable prevent-self-review only with a reviewer other than the release initiator; a sole maintainer needs an explicitly agreed self-approval policy or a second reviewer. Protect release tags and `main` as appropriate. A YAML environment name alone does not establish these protections. - Configure near the approved next release: a new publisher expires unless it successfully publishes within two days. Use GitHub-hosted runners. Public GitHub/public npm OIDC releases receive automatic provenance. -- After verifying protections and npm configuration, separately enable `NPM_PUBLISH_ENABLED=true`. Publishing the next GitHub release starts the workflow; environment approval releases the reviewed candidate. No npm token secret is required. +- After verifying protections and npm configuration, separately set the repository Actions variable `NPM_PUBLISH_ENABLED=true` (not an environment variable: the candidate job checks it before entering `npm`). Publishing the next GitHub release starts the workflow; environment approval releases the reviewed candidate. No npm token secret is required. Creating persistent trust, enabling automatic publication, and approving a specific release are separate actions. None has been performed by preparing these files. Changing existing npm publishing-access settings or revoking credentials also requires its own authorization. diff --git a/docs/USAGE.md b/docs/USAGE.md index e16508e..c659bd6 100644 --- a/docs/USAGE.md +++ b/docs/USAGE.md @@ -30,7 +30,7 @@ To try unreleased repository changes before publication, build and install a loc # In this repository: npm pack # In your project, substituting the actual archive path: -npm install --save-dev /path/to/agent-axiom-streamsplit-0.1.0.tgz +npm install --save-dev /path/to/agent-axiom-streamsplit-0.1.1.tgz ``` The [20-second visual demo](assets/demo.gif) is rendered from real synthetic-fixture output. Reproduce the underlying checks with `npm run demo:short`; regenerate the optional animation with `npm run build && python3 scripts/render-demo.py` (Python/Pillow and DejaVu fonts required only for rendering). diff --git a/package-lock.json b/package-lock.json index 2eb54a0..bbfc117 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@agent-axiom/streamsplit", - "version": "0.1.0", + "version": "0.1.1", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@agent-axiom/streamsplit", - "version": "0.1.0", + "version": "0.1.1", "license": "MIT", "devDependencies": { "@streamparser/json": "0.0.26", diff --git a/package.json b/package.json index 32af929..8861f58 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@agent-axiom/streamsplit", - "version": "0.1.0", + "version": "0.1.1", "description": "Find and shrink byte-chunking bugs in streaming parsers.", "type": "module", "license": "MIT", @@ -18,6 +18,7 @@ "dist", "docs", "README.md", + "CHANGELOG.md", "CONTRIBUTING.md", "AGENTS.md", "LICENSE" diff --git a/scripts/test-package.mjs b/scripts/test-package.mjs index b3d9322..29c21ed 100644 --- a/scripts/test-package.mjs +++ b/scripts/test-package.mjs @@ -14,6 +14,7 @@ try { assert.ok(files.some(file => file.path === 'dist/index.js')); assert.ok(files.some(file => file.path === 'dist/index.d.ts')); assert.ok(files.some(file => file.path === 'LICENSE')); + assert.ok(files.some(file => file.path === 'CHANGELOG.md')); assert.equal(files.some(file => /^(test|examples|scripts|node_modules|\.github)\//.test(file.path)), false); writeFileSync(join(directory, 'package.json'), JSON.stringify({ private: true, type: 'module' })); execFileSync('npm', ['install', '--offline', '--ignore-scripts', '--no-audit', '--no-fund', join(directory, filename)], { cwd: directory, env, stdio: 'pipe' }); diff --git a/test/docs.test.mjs b/test/docs.test.mjs index 5193606..53c66cd 100644 --- a/test/docs.test.mjs +++ b/test/docs.test.mjs @@ -6,7 +6,7 @@ import { fileURLToPath } from 'node:url'; import { execFileSync } from 'node:child_process'; const root = fileURLToPath(new URL('../', import.meta.url)); -const documents = ['README.md', 'CONTRIBUTING.md', 'AGENTS.md', ...readdirSync(join(root, 'docs')).filter(name => name.endsWith('.md')).map(name => `docs/${name}`)]; +const documents = ['README.md', 'CHANGELOG.md', 'CONTRIBUTING.md', 'AGENTS.md', ...readdirSync(join(root, 'docs')).filter(name => name.endsWith('.md')).map(name => `docs/${name}`)]; test('human and agent documentation links resolve locally', () => { for (const document of documents) { @@ -61,3 +61,14 @@ test('installation guides use the published package as a development dependency' assert.doesNotMatch(usage, /not published to the npm registry yet/i); assert.match(usage, /not included in the npm archive/); }); + + +test('release metadata and packaged changelog match the current version', () => { + const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')); + const lock = JSON.parse(readFileSync(join(root, 'package-lock.json'), 'utf8')); + assert.equal(lock.version, pkg.version); + assert.equal(lock.packages[''].version, pkg.version); + assert.equal(lock.packages[''].name, pkg.name); + assert.ok(pkg.files.includes('CHANGELOG.md')); + assert.ok(readFileSync(join(root, 'CHANGELOG.md'), 'utf8').includes(`## ${pkg.version}\n`)); +});