Development

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, 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.

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.