morphit/node_modules/@beblurt/dblurt/guide/maintainer-workflows.md

Maintainer workflows

Question answered by this guide: how should maintainers build, validate and publish generated developer-facing assets without confusing source and generated files?

This guide documents repository-level workflows around builds, generated API documentation, examples, AI context and coverage.

Documentation architecture

Path	Role	Rule
README.md	public landing page	short, attractive, links to specialized guides
guide/	hand-written developer guides	canonical human source of truth
ai/	AI-specific context/rules	thin layer; link to guide/ and examples/, do not duplicate them
examples/	product examples	executable evidence; safe blockchain query examples first
architecture/	reference architecture and decisions	update only for durable decisions, not routine notes
docs/	generated TypeDoc site	regenerated by make docs; do not edit by hand
lib/, dist/	generated build outputs	produced by build targets; do not edit by hand
coverage/	generated coverage report	local/CI output; do not edit by hand

make docs removes docs/ and regenerates it from TypeScript sources plus the Markdown files in guide/ through TypeDoc projectDocuments.

Documentation entropy rules

Treat documentation as production code with explicit ownership for facts.

Fact class	Canonical source	Documentation rule	Validation
Package version / current release	package.json, npm registry, CHANGELOG.md for history	Do not repeat the current version in evergreen guides, README, AI files or SECURITY.md.	npm run docs:check rejects source-doc literals such as @beblurt/dblurt@<current-version>.
Node/runtime target	package.json engines.node	Summarize and link to runtime compatibility; do not scatter independent matrices.	runtime-compatibility.md must point to package metadata fields.
Browser target	package.json browser and browserslist; generated dist/	Do not copy browser version lists; use Browserslist to resolve exact targets.	docs:check verifies the runtime guide references browserslist.
TypeScript declaration contract	package.json types/typings, generated declarations, package tests	Do not document a one-off smoke-test compiler version as a public compatibility minimum.	docs:check rejects “TypeScript x.y.z used by project” wording.
API signatures	TypeScript source and generated TypeDoc	Guides may explain routing; exact signatures belong to TypeDoc/source.	TypeDoc generation and tests.
Examples	files under examples/ plus their metadata comments	Guide pages should link to the canonical catalog instead of duplicating every row.	docs:check verifies every example file is listed in examples/README.md.
Security model	architecture/SECURITY_ARCHITECTURE.md, SECURITY.md, source/tests for implementation behavior	Keep evergreen guidance stable; put release-specific audit output in reports, not guides.	docs links + regular tests/audit commands.

When a factual claim cannot be tied to one of these sources, label it as inferred/unverified or remove it.

TypeDoc integration

The project currently uses TypeDoc with:

entryPoints: src/index.ts
projectDocuments: guide/*.md
out: docs

Current TypeDoc role:

• generate the API reference site;
• include human guide pages inside the generated site;
• keep editorial Markdown outside the generated output.

Current rule:

TypeDoc output is generated. `docs/` is not a source documentation directory.

TypeDoc evolution notes

Do not migrate away from TypeDoc in routine documentation work.

Future TypeDoc outputs worth evaluating, in order:

1. JSON reflection output for API metadata and documentation validation.
2. API symbol index generated from TypeDoc JSON.
3. Markdown API output for future site/AI ingestion.
4. Generated llms.txt / SKILL.md only after TypeDoc/plugin compatibility is proven.

Potential future generated inputs for AI:

Output	Future use
TypeDoc JSON	API metadata, symbol lookup, API coverage, generated summaries
TypeDoc Markdown	llms-full.txt, docs site pages, AI retrieval
API symbol index	hallucination prevention and quick lookup
Documentation coverage report	missing public API docs/examples

Current caution:

Some modern TypeDoc AI plugins require newer TypeDoc versions than the project currently uses. Evaluate plugin peer dependencies before adding them.

TypeDoc warning remediation plan

Current warning classes observed during the documentation quality pass:

Class	Status	Remediation
Legacy tags (@file, @description, @brief, @ingroup, @note)	mostly remediated where reported by TypeDoc	Replace with normal prose when files are touched. Do not add TypeDoc suppressions.
Incorrect @param names	mostly remediated where reported by TypeDoc	Keep parameter names exactly aligned with function signatures. For object parameters, document the object parameter and its exported interface fields.
Broken {@link ...} targets	mostly remediated where reported by TypeDoc	Prefer plain text or a valid exported symbol. Do not link to private implementation details.
Referenced public property type not included	open	Client.broadcast references BroadcastAPI, and experimental/core options reference internal core adapter shapes. Fix only after deciding whether exporting those symbols is a public API change.

Current policy:

• report TypeDoc warnings in every documentation quality pass;
• fix factual JSDoc issues when safe;
• do not silence warnings;
• do not expand public API just to satisfy TypeDoc without maintainer approval.

Build pipeline

The build has one TypeScript compilation path. make lib runs tsc and emits CommonJS-compatible JavaScript under lib/ plus lib/version.js. The TypeScript configuration uses Node-style module semantics so native dynamic import() is preserved where runtime lazy loading is required.

The browser bundle is generated from the compiled browser entrypoint:

src/ -> tsc -> lib/index-browser.js -> browserify -> dist/dblurt.js

Do not reintroduce a second TypeScript compiler path for the browser bundle unless there is a concrete compatibility reason. The browser bundle should stay reproducible from lib/, and npm run csp:check should continue to prove that generated runtime artifacts do not contain unsafe-eval constructs such as eval() or new Function().

Publication strategy

Do not publish documentation manually from a local checkout.

Recommended future publication flow:

source docs + examples + TypeDoc config
        |
        v
validation jobs
        |
        v
generated API docs / AI indexes / site output
        |
        v
GitLab Pages public artifact

npm run docs:site:build and npm run docs:public:build both regenerate AI retrieval surfaces before building the VitePress site. VitePress copies static files from site/public/ to the output root, and the VitePress build hook copies generated root publication assets such as llms.txt and llms-full.txt into the same output directory. Deployment should not require a manual post-build copy step for root publication assets.

Near-term publication should keep raw TypeDoc output viable. A later GitLab Pages job can publish docs/ or a public/ artifact without changing the source documentation model.

Future GitLab Pages candidates:

Output	Publish when
TypeDoc HTML	after docs validation exists
llms.txt	after canonical URLs are stable
llms-core.txt / llms-full.txt	after generated assembly exists
TypeDoc Markdown/site output	after site framework decision, if any
coverage reports	only if maintainers want public coverage visibility

Documentation validation workflow

The validation workflow is intentionally staged. It does not need to be fully implemented before every documentation change, but future CI should move toward it.

For documentation-only work, the consolidated entry point is:

npm run docs:check

It validates Markdown links, fenced-code balance, AI-layer hygiene, example metadata, blockchain query Node examples, TypeScript example compilation, and TypeDoc generation to /tmp without modifying docs/.

For release-oriented maintenance work, use:

npm run release:check

That command runs typecheck, lint, tests, build, CI-safe documentation checks, AI documentation freshness, CSP runtime scanning and npm package tarball validation.

If public RPC endpoints are unavailable, skip live examples while keeping static checks active:

DBLURT_DOCS_CHECK_SKIP_LIVE_EXAMPLES=1 npm run docs:check

Stage 1: Markdown structure

Validate:

• files exist for relative Markdown links;
• code fences are balanced;
• generated directories are not hand-edited in documentation PRs;
• forbidden project claims do not appear.

Examples of forbidden or risky claims:

• calling dblurt the official Blurt SDK without proof;
• claiming unsupported runtimes;
• presenting Nexus Layer 2 data as Layer 1 consensus truth.

Stage 2: Executable examples

Validate safe examples first:

node examples/node/read-head-block.cjs
node examples/node/read-block-operations.cjs
node examples/node/read-account.cjs
node examples/node/read-post.cjs
node examples/node/read-active-votes.cjs
node examples/node/read-witness.cjs
node examples/node/read-account-history.cjs
node examples/node/stream-block-numbers.cjs
node examples/node/read-nexus-ranked-posts.cjs
node examples/node/read-nexus-community.cjs
node examples/node/generic-call.cjs

Rules:

• blockchain query examples may run against public RPC endpoints;
• examples requiring keys must not run by default;
• broadcast examples must remain opt-in and safety-reviewed.

Stage 3: TypeScript examples

Compile TypeScript examples without emitting output:

npx tsc --noEmit --target ES2020 --module commonjs --moduleResolution node examples/typescript/read-account.ts

A future validation script should centralize this command and avoid relying on ad-hoc shell invocations.

Stage 4: TypeDoc and generated docs

Validate:

npm run docs

Expected behavior:

• docs/ is regenerated;
• no hand edits are made inside docs/;
• TypeDoc warnings are reported, not ignored.

Future improvement:

• establish a TypeDoc warning baseline;
• fail CI only on new warnings after the baseline is known.

Stage 5: AI documentation consistency

Validate:

• ai/ links to guide/ and examples/ instead of duplicating them;
• AI files do not contain stale copied guide sections;
• AI rules match package metadata and runtime compatibility docs;
• future llms.txt links point to canonical public URLs.

Stage 6: Runtime and package guardrails

Validate generated runtime and package surfaces after build or packaging changes:

npm run csp:check
npm run package:check

csp:check scans generated runtime JavaScript under lib/ and dist/dblurt.js for constructs that require unsafe-eval. package:check packs the npm payload, verifies required files and installs the tarball into a temporary CommonJS consumer smoke test.

Stage 7: Documentation freshness

Future freshness checks should detect:

• guide examples that no longer match examples/ files;
• API guide entries for methods that no longer exist;
• examples that use removed exports;
• TypeDoc output not regenerated after public API changes;
• AI context not updated after runtime/package changes.

Make targets

Target	Status	Purpose
make all	active	build library, browser bundle and generated docs
make lib	active	compile TypeScript into lib/ and generate lib/version.js
make bundle	active	generate dist/dblurt.js, dist/dblurt.js.gz and dist/dblurt.d.ts
make docs	active	regenerate the TypeDoc site under docs/
make docs-check	active	validate source docs, AI context, examples and TypeDoc warning baseline without writing generated docs
make test	active	local Mocha test runner, supports grep=...
make ci-test	active	lint plus c8 LCOV test run used by npm test
make lint	active	ESLint over src/**/*.ts
make typecheck	active	tsc --noEmit validation
make coverage	active	HTML/text/LCOV coverage report for local inspection
make clean	active	remove generated lib/, dist/*, docs/ and coverage/
make distclean	active	clean plus node_modules/ removal

Historical browser test targets existed in the initial Makefile but depended on Karma/Sauce tooling that is no longer present in current package.json. They should not be restored without adding and validating a modern browser test stack.

Coverage

make coverage uses c8 rather than the historical nyc stack.

It generates:

• terminal text coverage;
• HTML coverage under coverage/;
• LCOV coverage under coverage/lcov.info.

The target excludes test/** and scripts/** so the report focuses on library code. The CI-oriented make ci-test still generates LCOV output with TAP test reporting.

Release commands

npm run release:check is the side-effect-free release preflight. Run it before proposing a package release or merging release-sensitive build/package changes.

npm run release delegates to commit-and-tag-version. It can create local release commits and tags. Do not run it during documentation, DX, validation or audit work unless release side effects are explicitly authorized.