@resistdesign/voltra 3.0.0-alpha.0 → 3.0.0-alpha.10

package/README.md

@@ -1,6 +1,6 @@
 # Voltra
 
-![Voltra Logo Inverse 2025.svg](https://docs.voltra.app/images/Voltra%20Logo%20Inverse%202025.svg "Voltra")
+![Voltra Logo 2025.svg](https://docs.voltra.app/images/Voltra%20Logo%202025.svg "Voltra")
 
 ------------
 
@@ -14,6 +14,57 @@
 yarn add @resistdesign/voltra
 ```
 
+### Imports
+
+Prefer the public entrypoints below to keep imports stable and IDE auto-imports clean.
+
+Preferred:
+
+```ts
+import {IaC} from "@resistdesign/voltra";
+import {Packs} from "@resistdesign/voltra/iac";
+import {addDNS} from "@resistdesign/voltra/iac/packs";
+```
+
+Not supported:
+
+```ts
+import addDNS from "@resistdesign/voltra/iac/packs/dns";
+```
+
+Public entrypoints:
+
+- `@resistdesign/voltra`
+- `@resistdesign/voltra/api`
+- `@resistdesign/voltra/app`
+- `@resistdesign/voltra/common`
+- `@resistdesign/voltra/iac`
+- `@resistdesign/voltra/iac/packs`
+
+------------
+
+## Build-time Type Parsing (Advanced)
+
+Voltra exposes TypeScript compiler–powered parsing utilities intended **only for build-time tooling** (scripts,
+generators, CI).
+
+These APIs depend on the TypeScript compiler and **must not be imported into runtime code** (e.g. Lambdas, servers,
+browsers).
+
+Build entrypoint:
+
+```ts
+import {getTypeInfoMapFromTypeScript} from "@resistdesign/voltra/build";
+```
+
+Use this entrypoint for:
+
+- Code generation
+- Pre-build analysis
+- Producing static artifacts (JSON / TS)
+
+Do **not** import `@resistdesign/voltra/build` from runtime code.
+
 ## With our powers combined!
 
 <table style="border: 0 solid black;">
@@ -26,7 +77,7 @@ features like chainable stacks and comprehensive parameter support. Its intuitiv
 databases, storage, authentication, and functions through easy-to-use packs. Furthermore, Voltra enhances development
 workflows with advanced state management, and a smart, lightweight routing system for React
 front-end apps.</td>
-<td><img src="https://docs.voltra.app/images/Voltra%20Robot%20Coming%20Together.png" style="width: 200em;" /></td>
+<td><img src="https://docs.voltra.app/images/Voltra%20Incarnate.png" style="width: 400em;" /></td>
 </tr>
 </tbody>
 </table>
@@ -41,6 +92,40 @@ front-end apps.</td>
 | ORM: TypeScript Type Driven Auto-generated Data Contexts with Relationships |                                               | Typed Build Spec Creation                                     |
 |                                                                             |                                               | Typed Resource Parameters                                     |
 
+## Docs Site
+
+The docs site is both reference documentation and a canonical usage example.
+Key pieces:
+
+- Astro app in `site/app` builds the UI into `site-dist/app` via `yarn site:build:app`.
+- API bundle for the docs site is built by `yarn site:build:api` (see `site/build-api.mjs`) and written to
+  `site-dist/api`.
+- The IaC demo template is generated by `yarn site:build:iac` from `site/iac/index.ts` and written to
+  `site-dist/iac/index.yml`.
+
+API docs flow:
+
+1) `yarn doc` generates TypeDoc output into `docs/`.
+2) `yarn doc-to-site` copies `docs/` into `site-dist/app/`.
+3) `yarn site:build:app` runs Astro and then `yarn finalize-site` to refresh the docs site with API docs.
+
+## IaC Type Generation
+
+IaC types are generated from the AWS CloudFormation resource specification.
+When updating, follow this flow:
+
+1) Download the latest CloudFormation resource specification JSON from AWS (region: `us-east-1`).
+2) Replace the contents of `src/iac/types/CloudFormationResourceSpecification.ts` with the JSON payload (as the exported
+   data).
+3) Run `yarn iac:types:gen` to regenerate `dist/IaCTypes.ts`.
+4) Verify `dist/IaCTypes.ts` looks correct, then commit both files.
+
+Notes:
+
+- `src/iac/types/IaCTypes.ts` and `src/iac/types/CloudFormationResourceSpecification.ts` are generated artifacts; do not
+  edit by hand.
+- The generator entrypoint is `src/iac/types/generate.ts` and uses `src/iac/types/Renderers.ts` for output.
+
 ## Releasing
 
 Voltra publishes npm packages from GitHub Releases. The release tag is used verbatim
@@ -68,5 +153,24 @@ When the GitHub Release is marked as a prerelease, the npm publish step uses the
 `next` dist-tag instead of `latest`. Consumers can install prereleases with:
 
 ```bash
-npm install @resistdesign/voltra@next
+yarn add @resistdesign/voltra@next
 ```
+
+## Project
+
+### Build and test commands
+
+```bash
+yarn build
+yarn test
+yarn test:gen
+yarn doc
+yarn start
+yarn site:build:app
+```
+
+### Contribution guidelines
+
+- Use Conventional Commits (`feat:`, `fix:`, `doc:`, `chore:`) with optional scopes.
+- Keep subjects imperative and concise.
+- Include test commands run (or reasons for skipping) in PR descriptions.