build: guard postinstall; fix: snapshot values in doctest rule

[Planeshifter]

Description

What is the purpose of this pull request?

This pull request fixes two persistent CI failures found on develop in a
routine sweep of the last 24h of GitHub Actions runs. Both landed on one
branch/PR because this session was constrained to a single designated
branch; they are otherwise unrelated fixes and are kept as separate commits.

• postinstall fails on every real npm install. The weekly
  test_published_package workflow has failed 6 consecutive runs (every
  run since 2026-06-07) with sh: 1: tools/scripts/apply_patches: not found (exit 127). package.json's postinstall hook runs
  tools/scripts/apply_patches to patch dev dependencies from
  etc/patches/, but .npmignore has excluded /tools/ (and /etc/)
  from the published npm package since 2021 — well before the
  postinstall hook was added in December 2025. Any npm install of
  @stdlib/stdlib from the registry (not a git checkout) fails outright,
  since the referenced script never exists in the installed tree. Fixed
  by guarding the hook so it no-ops when the script is absent, while
  still running (and propagating the real exit code of) apply_patches
  for contributors who install from a git checkout.

• Spurious doctest lint failures on docs/repl.txt. lint_changed_files
  failed on a new package, stats/incr/nanmeanvar, reporting 4 "doctest"
  mismatches that all claimed the expected value was the final example's
  result, even for lines documenting earlier intermediate values. The
  documented values are mathematically correct (verified independently via
  Welford's algorithm, and corroborated by an unrelated open PR, docs: clean-up #13435,
  whose reviewers found no fault with nanmeanvar's docs). Root cause: the
  doctest lint rule (@stdlib/_tools/repl-txt/rules/doctest, used for
  every package's docs/repl.txt in CI) captured each REPL example's
  return value as a live reference (scope[varName]) rather than a
  snapshot. Accumulator-style packages such as stats/incr/meanvar
  intentionally mutate and return the same output array on every call,
  so by the time the rule compared captured values against the documented
  text, every captured reference pointed at the same, already-mutated
  final state — producing false positives for any chained-call
  accumulator example. Fixed by snapshotting each captured value with
  @stdlib/utils/copy at capture time.

Related Issues

Does this pull request have any related issues?

No.

Questions

Any questions for reviewers of this pull request?

No.

Other

Any other information relevant to this pull request? This may include screenshots, references, and/or implementation notes.

Failing runs:

• postinstall: https://github.com/stdlib-js/stdlib/actions/runs/29173854732
• doctest rule: https://github.com/stdlib-js/stdlib/actions/runs/29180627893

Validation: No local node_modules were available in this environment
to run make lint-pkg-json or the full lint tool end-to-end (it
transitively requires third-party packages, e.g. debug, via
@stdlib/namespace). Instead:

• postinstall: verified package.json remains valid JSON; directly
  exercised the new shell guard under sh -c in three scenarios — script
  present, script absent, and script present-but-failing — confirming exit
  0 (no-op) only when absent, and the real exit code otherwise.
• doctest rule: verified @stdlib/utils/copy loads standalone and
  correctly deep-clones arrays/primitives/undefined/null without
  mutation leakage; reproduced the exact reference-aliasing failure mode
  (and confirmed the fix) in an isolated vm-based script mirroring the
  rule's example-execution loop; manually recomputed nanmeanvar's
  documented values via Welford's algorithm to confirm they were correct
  all along.

Three independent reviewers (correctness, regression-scope, style — two
Opus, one Sonnet) evaluated both fixes against the original job logs, root
cause, and diff. All three approved both fixes with no blocking findings.

Reviewer notes:

• (addressed) postinstall's original A && B || true form silently
  swallowed a genuine apply_patches failure, not just its absence;
  switched to if/fi so the real exit code still propagates when the
  script is present.
• (addressed) the doctest rule's explanatory comment was reflowed from a
  single ~180-char line to stdlib's usual ~80-column wrapping.
• (open, non-blocking) copy() in the doctest rule is applied
  unconditionally to every captured value. For the common cases —
  primitives, plain arrays/objects, standard typed arrays, Date,
  RegExp, Error, complex scalars — this is verified safe. For a few
  exotic container types not in @stdlib/utils/copy's typed-array hash
  (e.g. Complex64Array/Complex128Array, BooleanArray, ndarray),
  cloning falls back to a documented-as-"fragile" generic instance clone.
  This could theoretically produce a false doctest failure if some other
  package's docs/repl.txt documents a chained accumulator returning one
  of those types. Low probability, and not exercisable end-to-end in this
  environment (no node_modules) — worth a maintainer spot-check against
  a docs/repl.txt using one of those types before merge.

Two further CI failures from the same 24h window were investigated and
found to be intermittent (network/timing flakes), not fixed here per the
routine's classification criteria; see the local report for detail.

Checklist

Please ensure the following tasks are completed before submitting this pull request.

• Read, understood, and followed the contributing guidelines.

AI Assistance

When authoring the changes proposed in this PR, did you use any kind of AI assistance?

• Yes
• No

If you answered "yes" above, how did you use AI assistance?

• Code generation (e.g., when writing an implementation or fixing a bug)
• Test/benchmark generation
• Documentation (including examples)
• Research and understanding

Disclosure

If you answered "yes" to using AI assistance, please provide a short disclosure indicating how you used AI assistance. This helps reviewers determine how much scrutiny to apply when reviewing your contribution. Example disclosures: "This PR was written primarily by Claude Code." or "I consulted ChatGPT to understand the codebase, but the proposed changes were fully authored manually by myself.".

This PR was authored by Claude Code as part of a scheduled routine that
reviews the last 24h of GitHub Actions failures on develop, classifies
them as intermittent or persistent, and proposes fixes for persistent
failures. Root cause for each fix was traced by reading source, git
history, and CI logs, and independently validated with isolated
reproduction scripts (not the full test suite, which could not be run in
this environment). Three independent Claude reviewer passes (correctness,
regression-scope, style) evaluated both fixes before this PR was opened.

---

@stdlib-js/reviewers

---

Generated by Claude Code

[kgryte]

@Planeshifter What is the plan now that the most recent npm version disables running postinstall scripts by default? I suppose we could run the script during make init.

[Planeshifter]

Hmm, given it's a postinstall script in the project for which one would run npm install, I don't think it will be skipped. The npm change targets scripts from dependencies (packages in node_modules), not the top-level project's own scripts. And we really only need this script for local development.