docs(m4): typedoc configs + npm publish workflow for acp sdk and cli#313
Merged
0xDevNinja merged 3 commits intomilestone/M4-indexer-api-gateway-sdk-alphafrom Apr 29, 2026
Merged
Conversation
scope: closes #100. titular m4 phase typedoc + publish 0.1.0-alpha to npm. what: - add typedoc + typedoc-plugin-markdown to root devDependencies and a per-package typedoc.json for @titular/acp-sdk and @titular/acp-cli; generated markdown is emitted to packages/<pkg>/docs/api/ (gitignored, not committed — regenerate per release with pnpm -F <pkg> docs). - enrich package.json metadata for npm visibility: keywords, homepage, bugs, repository (with directory pointer), author. version stays at 0.1.0-alpha.0. dependencies / devDependencies untouched in both package-level package.jsons to stay disjoint with #101. - add a docs npm script in each package wired to the local typedoc.json. - add a packages/<pkg>/README.md so npm displays a real landing page (subpath exports, error taxonomy, evm provider adapter interface, and the llm helpers entry point are all called out per the m4 brief). - new .github/workflows/publish-npm.yml: workflow_dispatch only with tag (alpha|beta|latest) and dry-run inputs, builds both packages then pnpm publish --provenance. permissions are id-token:write + contents:read so the npm registry can verify the github oidc claim. the manual trigger keeps a human in the loop while the surface is still moving in alpha. verify: - pnpm -F @titular/acp-sdk build|typecheck|lint|test : pass (149 tests, 97.2% stmt coverage) - pnpm -F @titular/acp-cli build|typecheck|lint|test : pass (118 tests, 92.3% stmt coverage) - pnpm -F @titular/acp-sdk docs : pass (2 cosmetic warnings) - pnpm -F @titular/acp-cli docs : pass (3 cosmetic warnings) - pnpm -F @titular/acp-sdk publish --dry-run --no-git-checks : pass (43.2 kB packed, 63 files, README included) - pnpm -F @titular/acp-cli publish --dry-run --no-git-checks : pass (35.4 kB packed, 51 files, README included) - biome check on all touched json : pass
addresses two pr #313 review blockers: - publish-npm.yml: `pnpm publish` does not read `NPM_CONFIG_PROVENANCE` (only `npm publish` does), so the env var was dead weight and made the intent unclear. drop it; the `--provenance` flag on `pnpm publish` is the actual switch (pnpm >= 8.6). also pin `npm@latest` before publish so the runner has npm cli >= 9.5, which provenance attestation requires. - undici: trivy flagged 5.29.0 (cve-2026-1526, cve-2026-2229, both high dos). pulled transitively via testcontainers in the e2e package. add a pnpm.overrides entry forcing undici to ^6.24.0 across the workspace and regenerate the lockfile. all undici resolutions now collapse to 6.25.0; sdk + cli builds and tests stay green (149/149 sdk, 118/118 cli).
the previous fix forced undici to ^6.24.0 via root pnpm.overrides to silence two trivy-flagged dos cves (cve-2026-1526, cve-2026-2229). that broke apps/web vitest: jsdom@29 imports the internal path `undici/lib/handler/wrap-handler.js` which was removed in undici 6.0.0 and only exists again in undici 7.x. with the override in place, vitest forks failed to spawn for every apps/web __tests__ file with module_not_found. drop the override. without it, jsdom resolves to its preferred undici@7.25.0 (no cves) and the only remaining undici 5.x copy is via testcontainers in @titular/acp-sdk-e2e — a private workspace package only loaded by integration suites that talk to a local docker socket in ci. it never reaches the published acp-sdk / acp-cli runtime, the gateway, or the indexer binary, so both dos cves are not exploitable in our threat model. instead, add the two cves to .trivyignore alongside the existing dockertest chain, with a rationale block explaining the test-only dependency path and a note to re-audit when testcontainers ships a release that targets undici >=6. verified: - pnpm install --no-frozen-lockfile clean - pnpm -F @titular/web test: 65/65 pass (was 0/0 with 3 worker-spawn errors)
Owner
Author
|
LGTM — review blocker + CI addressed across two fixes. Verified:
Follow-ups (non-blocking):
Squash-merging into |
0xDevNinja
merged commit 54e7f7e
into
milestone/M4-indexer-api-gateway-sdk-alpha
23 checks passed
7 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Closes #100. M4 phase: TypeDoc + publish 0.1.0-alpha to npm.
typedoc.jsonfor@titular/acp-sdkand@titular/acp-cli, usingtypedoc-plugin-markdownfor markdown output. Generated underpackages/<pkg>/docs/api/, gitignored — regenerate per release withpnpm -F <pkg> docs. SDK config covers all four entry points (root,providers/alchemy,llm,session-keys); custom scalars, error codes, theEvmProviderAdapterinterface, and the LLM helpers entry point are all documented.keywords,homepage,bugs,repository(withdirectorypointer for monorepo), andauthorto both packages. Per-packagedependencies/devDependenciesdeliberately untouched to stay disjoint with integration tests: SDK against anvil fork + indexer + gateway #101 (parallel branch may add vitest integration deps). Version stays at0.1.0-alpha.0.fileswhitelist already correct (["dist", "README.md"]).packages/acp-sdk-ts/README.mdandpackages/acp-cli/README.mdso npm displays a real landing page. Covers install, quick start, subpath exports, error taxonomy, and provider-adapter contract..github/workflows/publish-npm.yml—workflow_dispatchonly (manual; alpha quality wants human-in-the-loop), withtag(alpha/beta/latest) anddry-runinputs. Builds both packages, thenpnpm publish --provenance --access public --no-git-checks. Permissions areid-token: write+contents: readso the runner can mint the OIDC token npm uses to verify provenance. Usessecrets.NPM_TOKEN.typedocandtypedoc-plugin-markdownto root devDependencies (per-package devDeps reserved for integration tests: SDK against anvil fork + indexer + gateway #101).Verify
pnpm -F @titular/acp-sdk build|typecheck|lint|testpnpm -F @titular/acp-cli build|typecheck|lint|testpnpm -F @titular/acp-sdk docspnpm -F @titular/acp-cli docspnpm -F @titular/acp-sdk publish --dry-run --no-git-checkspnpm -F @titular/acp-cli publish --dry-run --no-git-checkspublish-npm.ymlVerify log:
.claude/cron/last-verify-M4-typedoc-publish.log.Test plan
pnpm publish --dry-runsucceeds for both packages with READMEs includedtestworkflow)publish-npmmanually withdry-run=truefirst to confirm the runner can authenticate; then run for real withtag=alphaNotes
@linkresolution, internal opts types not exported, one relative README link). All non-blocking. Cleanup deferred so this PR stays focused on infra.docsscript touched inpackages/<pkg>/package.json; nodependencies/devDependenciesedits there.feat/M4-sdk-integration-testsby an auto-checkout hook mid-session and corrected via cherry-pick ontofeat/M4-typedoc-publish; the sibling branch was restored to its pre-clobber state (origin's milestone base) so integration tests: SDK against anvil fork + indexer + gateway #101's agent is unaffected.