Skip to content

Development

Jump to bottom
dweller long gone edited this page May 28, 2026 · 6 revisions

Development

This page summarizes local development and package conventions for ASN.1 Instance Builder.

Project Shape

Key files:

  • src/core.ts: public core API barrel for schema parsing, diagnostics, DER building, byte helpers, OID helpers, and PkiStudioJS adapter helpers.
  • src/core/: UI-independent ASN.1 schema model, parser, diagnostics, DER encoder, and instance builder implementation.
  • src/core/pki-components.ts: shared PKI ASN.1 definition text exported for other PkiStudio packages.
  • src/app.ts: browser app package entry.
  • src/app/main.ts: browser application shell, Definition pane, hybrid Form/JSON Instance Input pane, Diagnostics pane, API Log, NamedObjects loading, and standalone PkiStudioJS viewer routing.
  • src/viewer.ts: standalone PkiStudioJS viewer entry for viewer.html.
  • src/types/: local typings for raw bundled assets and @pkistudio/pkistudiojs imports.
  • src/styles/styles.css: application and viewer-host styling.
  • vite.config.ts: library build configuration and version injection.
  • vite.app.config.ts: browser app and standalone viewer build configuration.
  • fixtures/: ASN.1 definitions and matching instance JSON samples used by tests and NamedObjects.
  • test/: Vitest coverage for parser, diagnostics, DER behavior, and fixtures.

Local Checks

Run these before handing normal code changes back:

npm run check
npm test
npm run build

For package or release-related changes, also run:

npm run pack:dry-run

Local Development Server

npm run dev -- --port 5173 --strictPort

Then open:

http://localhost:5173/

In VS Code, the Start asn1instancebuilder server task starts the same server.

Wiki Preview in Codespaces

The repository devcontainer can prepare Gollum and clone the GitHub Wiki repository into:

/workspaces/asn1instancebuilder.wiki

Start the local Wiki preview with the VS Code task:

Start asn1instancebuilder wiki

Gollum listens on port 4567.

The setup script is:

.devcontainer/setup-wiki.sh

It installs gollum when needed and clones:

https://github.com/pkistudio/asn1instancebuilder.wiki.git

Package Entry Points

The npm package is @pkistudio/asn1instancebuilder.

Exports:

  • @pkistudio/asn1instancebuilder: dist/index.js.
  • @pkistudio/asn1instancebuilder/core: dist/core.js.
  • @pkistudio/asn1instancebuilder/app: dist/app.js.
  • @pkistudio/asn1instancebuilder/styles.css: dist/asn1instancebuilder.css.

Published type declarations are emitted under dist/types, including the core public type entry at dist/types/core.d.ts.

Version Metadata

When bumping versions, keep version metadata synchronized across:

  • package.json.
  • package-lock.json.
  • README.md.
  • Wiki references to the current package version when appropriate.

The package version is used for __ASN1_INSTANCE_BUILDER_VERSION__, the app About display, and release metadata.

Dependency Boundaries

Keep the package browser-first and host-neutral.

  • VS Code-specific file access, dialogs, persistence, and Webview lifecycle should remain outside this package.
  • Reusable ASN.1 parsing, schema diagnostics, instance diagnostics, DER encoding, byte helpers, and OID helpers belong under src/core/.
  • Shared PKI ASN.1 definition text belongs under src/core/ so related PkiStudio packages can consume the same baseline.
  • UI-specific browser behavior belongs in src/app/main.ts.
  • Do not introduce Node-only runtime dependencies into code shipped to the browser.
  • Use @pkistudio/pkistudiojs as an external dependency for library builds.

NamedObjects and Fixtures

Bundled NamedObjects should stay aligned with checked-in .asn1 and .instance.json fixtures.

Parent objects belong in the Load -> NamedObjects menu. Child objects should be selectable from the Instance Input type selector after the parent definition loads.

Release Notes

Release work normally follows a PR path: branch, focused commit, push, PR, CI, merge, annotated tag, GitHub Release, npm publication, and verification.

GitHub Release names should use the tag only, such as v0.1.9. Do not prefix the product name in the GitHub Release title. WordPress release posts can still use the product-specific title pattern handled by the release workflow.

Verify published package state with:

npm view @pkistudio/asn1instancebuilder@<version> version dist-tags dist.tarball --json

ASN.1 behavior changes should prefer structured schema, parser, diagnostics, and DER helpers over ad hoc string or byte manipulation.

ASN.1 Instance Builder

Links

Clone this wiki locally