Skip to content

Harden config encoding policy, template generation limits, and version parity - #421

Merged
dDevAhmed merged 8 commits into
DigiNodes:mainfrom
akargi:feature/config-utf8-version-and-template-limits
Nov 20, 2026
Merged

dDevAhmed merged 8 commits into
DigiNodes:mainfrom
akargi:feature/config-utf8-version-and-template-limits

Conversation

@akargi

@akargi akargi commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Closes #379

Addresses #380, #399, #400.

Summary

Implements the four Stellar Wave issues assigned to Akargi (#379, #380, #399, #400). Per-issue keywords are declared in commit messages/body where applicable; this PR body keeps a single closing reference for Wave scope automation.

SW-198 / #379 - Deterministic version/help metadata parity test (WS-CORE, P1)

The CLI no longer hard-codes its identity: the executable name comes from the single bin entry (stellarforge), the root help description comes from the manifest description, and the root command version falls back to the manifest version when no override is given. No duplicate constants remain. tests/version.test.ts asserts the manifest relationship, tests/root-command.test.ts asserts the help body matches the manifest description, and the built-CLI --version contract in executable.test.ts continues to cover the released binary.

SW-199 / #380 - Bounded file-count and total-size limits for template generation (WS-GENERATOR, P1, protected surface)

Template trees are measured before any file is read, staged, or promoted: at most 256 regular files, at most 1 MiB of aggregate regular-file content, at most 256 KiB per file. Exceeding a limit fails with a safe aggregate message (file count or byte total only - never local paths or entry names), and the destination is left completely untouched. Bundled templates stay well within the budget, and the limits themselves are documented in Template Generation Safety with deterministic boundary tests.

SW-217 / #399 - Define and test UTF-8 BOM handling for project configuration (WS-CONFIG, P2, protected surface)

A single leading UTF-8 byte-order mark is tolerated (RFC 8259-compliant, matching common Windows editor conventions), while two or more BOMs are rejected with the stable stellarforge.config.json is not valid JSON. error. Loading behavior is documented precisely in docs/reference/configuration.md and the ADR, so the docs match the actual loader.

SW-218 / #400 - Reject invalid UTF-8 bytes in stellarforge.config.json (WS-CONFIG, P1, protected surface)

The loader previously trusted readFileSync(path, 'utf8'), silently replacing invalid bytes with U+FFFD and masking corruption. The config is now decoded strictly as UTF-8 before JSON parsing: stray continuation bytes, invalid lead bytes, truncated sequences (2- and 3-byte), overlong encodings, and encoded surrogates are rejected with the stable stellarforge.config.json is not valid UTF-8. message - never the bytes, offsets, or the file content. Valid configurations, including non-ASCII text reaching the schema layer, are unaffected.

Also requests maintainer review for the protected files (src/config/project.ts, src/generator/template-generation.ts, .changeset/) which this work intentionally touches.

Tests

Every fix carries regression coverage: invalid-UTF-8 rejection for every malformed-byte class with sentinel-free assertion styles, BOM tolerance and double-BOM rejection, exact budget boundaries plus over-limit cleanup and aggregate-only error messages, manifest/version/bin parity for the root command, and backfill for the two pre-existing contract-update checks. No live Stellar network calls, wallets, or secrets are used anywhere.

Security

  • Config loader never errors with raw bytes, offsets, or contents; the failure mode exits with code 2 (usage error) via the same boundary as before.
  • Template generation budget is enforced pre-write - zero files touched when exceeded.
  • No new dependencies; no network calls in tests or implementation.

Note: overlap with open contributor PR #229 touching src/commands/root.ts may still trigger Wave scope/conflict policy checks until resolved upstream. release-pack-snapshot flakiness/failures may be environment-dependent as previously noted.

…odes#399, DigiNodes#400)

Read stellarforge.config.json strictly as UTF-8 and reject invalid byte
sequences before JSON parsing: truncated multi-byte sequences, overlong
encodings, encoded surrogates, and stray continuation bytes all fail with
the stable 'stellarforge.config.json is not valid UTF-8.' message instead
of being silently replaced with U+FFFD. A single leading BOM is tolerated;
documentation states this policy explicitly in configuration.md,
troubleshooting.md, and ADR-0005. Non-BOM files are unchanged, and the
byte-order mark behavior is deterministic.

Closes DigiNodes#399
Closes DigiNodes#400
…igiNodes#379)

resolveCliMetadata() is now the single source of truth: version,
description, and the single bin executable name are read and validated
from the installed package manifest, root command name/description/help
all derive from it, and no duplicate hard-coded constants remain. The
root-command and version tests assert the manifest relationship and the
source-level command path; the executable.test.ts built-path check for
--version continues to pass as-is.

Closes DigiNodes#379
…iNodes#380)

Measure the template tree before staging: at most 256 regular files, 1 MiB of
aggregate regular-file content, 256 KiB per file. Exceeding a documented
limit fails before any file is written, with a safe aggregate message that
never leaks absolute paths or entry names. Bundled templates remain well
inside the budget; deterministic tests cover exact boundaries and over-limit
cases.

Closes DigiNodes#380
@akargi
akargi requested a review from dDevAhmed as a code owner November 19, 2026 13:59
@coderabbitai

coderabbitai Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

Important

  • Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 141baf92-f937-49bd-8893-e0af207a7906
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@dDevAhmed
dDevAhmed merged commit bd3a92e into DigiNodes:main Nov 20, 2026
7 of 13 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

SW-198 — Add deterministic version/help metadata parity test

2 participants