@powerhousedao/academy 2.5.0-dev.10 → 2.5.0-dev.12

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## 2.5.0-dev.12 (2025-06-10)
+
+This was a version bump only for @powerhousedao/academy to align it with other projects, there were no code changes.
+
+## 2.5.0-dev.11 (2025-06-07)
+
+### 🚀 Features
+
+- **connect:** updated diff-analyzer processor ([ce5d1219f](https://github.com/powerhouse-inc/powerhouse/commit/ce5d1219f))
+
+### ❤️ Thank You
+
+- acaldas
+
 ## 2.5.0-dev.10 (2025-06-06)
 
 ### 🚀 Features

package/docs/academy/02-MasteryTrack/05-Launch/02-PublishYourProject.md

@@ -202,15 +202,79 @@ If you're publishing a package under a scope (like @your-org/my-package), you mi
 }
 ```
 
-For the actual publishing step, run the following command to publish your project to the npm registry:
+### 2.1 Versioning, Tagging, and Publishing Your Package
+
+Before publishing, it's crucial to version your package correctly and tag the release in your Git repository. This helps track changes and allows users to depend on specific versions.
+
+**1. Versioning with PNPM**
+
+Use the `pnpm version` command to update your package version according to semantic versioning rules (`patch` for bugfixes, `minor` for new features, `major` for breaking changes). This command will:
+- Update the `version` in your `package.json`.
+- Create a Git commit for the version change.
+- Create a Git tag for the new version (e.g., `v1.0.1`).
+
+```bash
+# For a patch release (e.g., from 1.0.0 to 1.0.1)
+pnpm version patch
+
+# For a minor release (e.g., from 1.0.1 to 1.1.0)
+pnpm version minor
+
+# For a major release (e.g., from 1.1.0 to 2.0.0)
+pnpm version major
+```
+Take note of the new version tag created (e.g., `v1.0.1`), as you'll need it in the next step.
+
+**2. Pushing Changes to Git**
+
+Next, push your commits and the new version tag to your remote Git repository:
+
+```bash
+# Push your current branch (e.g., main or master)
+# Replace 'main' with your default branch name if different
+git push origin main
+
+# Push the specific tag created by pnpm version
+# Replace vX.Y.Z with the actual tag name (e.g., v1.0.1)
+git push origin vX.Y.Z
+```
+The specific tag name (e.g., `v1.0.1`) is usually output by the `pnpm version` command. Pushing the specific tag is recommended to avoid unintentionally pushing other local tags.
+
+Alternatively, to push all new local tags (use with caution):
+```bash
+# git push --tags
+```
+
+**3. Understanding Git Tags vs. NPM Distributor Tags**
+
+It's important to distinguish between Git tags and NPM distributor tags (dist-tags):
+
+-   **Git Tags**: These are markers in your Git repository's history. They are primarily for developers to pinpoint specific release versions in the codebase (e.g., `v1.0.0`, `v1.0.1`). The `pnpm version` command creates these.
+-   **NPM Distributor Tags (dist-tags)**: These are labels used by the NPM registry to point to specific published versions of your package. Common NPM tags include:
+    -   `latest`: This is the default tag. When someone runs `pnpm install my-package`, NPM installs the version tagged as `latest`.
+    -   `beta`, `next`, `alpha`: Often used for pre-release versions.
+    When you publish a package without specifying an NPM tag, it usually gets the `latest` tag by default.
+
+**4. Publishing to NPM**
+
+Now you are ready to publish your package to the NPM registry. Ensure you are logged into NPM (the `npm login` command shown in previous steps should be used, or `pnpm login` which is an alias).
+
+```bash
+pnpm publish
+```
+This command will publish the version of your package that is currently specified in your `package.json`. By default, this will also set the `latest` NPM dist-tag for this version.
+
+If your package is scoped (e.g., `@your-org/my-package`) and intended to be public, ensure your `package.json` includes the `publishConfig` shown earlier. If this is not set in `package.json` (and your package is scoped), you might need to use:
 ```bash
-npm publish
+pnpm publish --access public
 ```
 
-Optionally, if you are publishing a scoped package and you want it public, run:
+You can also publish a version to a specific NPM dist-tag. For example, to publish a beta version:
 ```bash
-npm publish --access public
+# Ensure your package.json version reflects the beta (e.g., 1.1.0-beta.0)
+pnpm publish --tag beta
 ```
+This is useful for testing releases before making them `latest`.
 
 Now let's verify that the package(s) get published in the package repository, next to pre-existing packages that you might have been publishing before.
 

package/docs/academy/02-MasteryTrack/05-Launch/03-SetupEnvironment.md

@@ -1,7 +1,8 @@
-# Powerhouse Setup Guide (WIP)
+# Powerhouse Setup Guide
 
 ## Introduction
-Powerhouse is a powerful platform that helps you manage and deploy your applications efficiently. This guide will walk you through the process of setting up both the Powerhouse CLI and configuring your server machine to run Powerhouse services. Whether you're setting up a development environment or preparing for production deployment, this guide provides all the necessary steps and considerations.
+Powerhouse is a powerful platform that helps you manage and deploy your applications efficiently.   
+This guide will walk you through the process of setting up both the Powerhouse CLI and configuring your server machine to run Powerhouse services. Whether you're setting up a development environment or preparing for production deployment, this guide provides all the necessary steps and considerations.
 
 ## Prerequisites
 Before you begin, ensure you have a Linux-based system (Ubuntu or Debian recommended), sudo privileges, and a stable internet connection. These are essential for the installation and configuration process. The system should have at least 1GB of RAM and 10GB of free disk space for optimal performance. While these are minimum requirements, more resources will provide better performance, especially when running multiple services.
@@ -12,6 +13,7 @@ The `install` script provides a streamlined way to install the Powerhouse CLI to
 
 
 ### Installation Steps:
+
 1. Run the setup script:
 ```bash
 curl -fsSL https://apps.powerhouse.io/install | bash # for macOS, Linux, and WSL
@@ -32,10 +34,14 @@ If you are a builder that wants to make use of the dev releases use `ph use dev`
    - `ph use dev`: Development version - Use this for testing new features or development work
    - `ph use staging`: Staging version - Use this for pre-production testing
 
-5. Follow the interactive prompts:
+5. Initialize your project with `ph init <project-name>` 
+
+6. Follow the interactive prompts that are appearing after having installed your first package. 
 
 ### Step 1: Package Installation
-During the package installation phase, you'll be prompted to enter package names that you want to install. For example, you might want to install `@powerhousedao/todo-demo-package` or other Powerhouse packages. This step is crucial for adding the specific functionality you need to your Powerhouse installation. You can press Enter to skip this step if you don't need to install any packages immediately, but you can always install packages later using the `ph install` command.
+During the package installation phase, you'll be prompted to enter package names that you want to install. For example, you might want to `ph install @powerhousedao/todo-demo-package` or other Powerhouse packages. This step is crucial for adding the specific functionality you need to your Powerhouse installation. 
+
+You can also press Enter to skip this step if you don't need to install any packages immediately, but you can always install packages later using the `ph install` command.
 
 ### Step 2: Database Configuration
 The script offers two options for database configuration. 
@@ -302,7 +308,7 @@ You can also use
 ```bash
 ph service start | stop | restart 
 ```
-- to start | stop | restart switchboard and connect
+to start | stop | restart switchboard and connect
 
 2. View Nginx configuration:
 ```bash

package/docs/academy/04-APIReferences/00-PowerhouseCLI.md

@@ -2,10 +2,12 @@
 
 ### Installing the Powerhouse CLI 
 :::tip
-The **Powerhouse CLI tool** is the only essential tool to install on this page. Install it with the command below. 
+The **Powerhouse CLI tool** is the only essential tool to install on this page. Install it with the command below.    
+
 You can find all of the commands on this page, similar to what would displayed when using ph --help or ph *command* --help. 
-Use the table of content or the search function to find what you are looking for.
-The Powerhouse CLI (`ph-cmd`) is a command-line interface tool that provides essential commands for managing Powerhouse projects. You can get access to the Powerhouse ecosystem tools by installing them globally using:
+Use the table of content or the search function to find what you are looking for.   
+
+The Powerhouse CLI (`ph-cmd`) is a command-line interface tool that provides essential commands for managing Powerhouse projects. You can get access to the Powerhouse ecosystem tools by installing them globally.
 
 ```bash
 pnpm install -g ph-cmd
@@ -208,7 +210,7 @@ Examples:
 
 ---
 
-*This document was automatically generated from the help text in the codebase.*\n\n### ph-cli Commands\n\n- [Connect Build](#connect-build)
+- [Connect Build](#connect-build)
 - [Connect Preview](#connect-preview)
 - [Connect Studio](#connect-studio)
 - [Dev](#dev)
@@ -702,39 +704,4 @@ Notes:
 
 ---
 
-*This document was automatically generated from the help text in the codebase.*\n<!-- AUTO-GENERATED-CLI-COMMANDS-END -->
-
-<details>
-<summary> How to make use of different branches? </summary>
-
-When installing or using the Powerhouse CLI commands you are able to make use of the dev & staging branches. These branches contain more experimental features then the latest stable release the PH CLI uses by default. They can be used to get access to a bugfix or features under development.
-
-| Command | Description |
-|---------|-------------|
-| **pnpm install -g ph-cmd** | Install latest stable version |
-| **pnpm install -g ph-cmd@dev** | Install development version |
-| **pnpm install -g ph-cmd@staging** | Install staging version |
-| **ph init** | Use latest stable version of the boilerplate |
-| **ph init --dev** | Use development version of the boilerplate |
-| **ph init --staging** | Use staging version of the boilerplate |
-| **ph use** | Switch all dependencies to latest production versions |
-| **ph use dev** | Switch all dependencies to development versions |
-| **ph use prod** | Switch all dependencies to production versions |
-
-Please be aware that these versions can contain bugs and experimental features that aren't fully tested.
-</details>
-
-
-the ph connect command now uses three subcommands:
-
-studio (default) — runs connect studio. since this is the default argument, running ph connect still has the same behavior as before,
-
-build — bundles the project's local and external model/editor code and injects the js/css into the already-built connect bundle for deployment,
-
-preview — runs the vite preview server with the output of build for testing purposes,
-
-running ph connect --help now lists the sub-commands. Running ph connect studio --help now shows the help for the studio command, likewise for the other new commands.
-
-This approach avoids redundant build/compilation which is great for minimizing server resource use. The only compilation that runs is the esbuild of the project code (does not need tsc as that is handled separately) and then tailwind for the local project styles. The whole thing takes less than a second, albeit on my macbook.
-
-This should just work with the current boilerplate since these are just new arguments to the existing ph-cli connect command. 
+*This document was automatically generated from the help text in the codebase.* <!-- AUTO-GENERATED-CLI-COMMANDS-END -->

package/docs/academy/06-ComponentLibrary/{03-Scalar-Components/01-phid-field.mdx → 02-ScalarComponent.mdx}

@@ -1,10 +1,60 @@
----
-sidebar_label: 'PHID Field'
-sidebar_position: 1
----
-
 import { Tabs, TabItem } from '@theme/Tabs';
 
+# E.g. Scalar Component
+
+Scalars are here to help you define custom fields in your document model schema and speed up the development process.
+There are two applications of scalar components in the document model workflow:
+
+1. At the **schema definition** level where you build your schema and write your GraphQL state schema.
+2. At the **frontend / react** level where you import it and place it in your UI to represent the scalar field
+
+## Scalar Definition in the Document Model Schema
+
+As you might know, the document model schema defines the structure of the document and serves as the backbone of the document model. The GraphQL state schema defines how data is captured with the help of types & scalars. When you define a scalar in the document model schema, you are essentially defining a new field that can be used in the document model to capture data.
+
+In the Document Model Editor, you can find all the custom scalar types available in our documentation under the 'Scalars' section.
+
+Insert image of the feature. 
+
+````
+scalar PHID <-- imported from the design system library? not sure
+type MyType {
+  myScalar: PHID
+}   
+````
+
+## React Component Implementation in the Frontend
+
+All of our reusable components are available in the Document-Engineering design system library or package.
+This package comes as a dependency in your project when creating a new document model project.
+````
+import PHIDField from 'document-engineering'
+const reactComponent = () => {
+
+return (
+  <div>
+    <PHIDField
+      fetchOptionsCallback={function Js(){}}
+      fetchSelectedOptionCallback={function Js(){}}
+      label="PHID field"
+      name="phid-field"
+      placeholder="phd:"
+    />
+
+  </div>
+  
+  )
+
+}
+````
+
+## Scalars & Reusable Components
+
+To make your life easier, Powerhouse has defined all useful scalars with a set of reusable code and UI components.
+The reusable components are essentially a set of front-end components based on GraphQL scalars. Powerhouse also has a set of custom scalars that are not part of the GraphQL standard but are specific to the web3 ecosystem.
+
+Read the next chapter to get familiar with our reusable components. 
+
 # PHID Field Example
 
 ### **Scalar Definition**
@@ -43,7 +93,7 @@ import { Tabs, TabItem } from '@theme/Tabs';
     - **Error Message Example:** "Invalid PHID format. Please check the document ID, branch, or scope."
 </details>
 
-The following is a the UI component for the PHID field and scalar in a storybook.
+The following is the UI component for the PHID field and scalar in a storybook.
 We use Storybook as our component development environment. 
 It allows us to build and test UI components in isolation, making it easier to develop, test, and document reusable components.
 In our stories you'll find first find a basic UI implementation example of the component, followed by the component's properties, events, and validation options.

package/docs/academy/06-ComponentLibrary/{04-Complex-Components/01-sidebar.mdx → 03-ComplexComponent.mdx}

@@ -1,6 +1,8 @@
 import { Tabs, TabItem } from '@theme/Tabs';
 
-# Sidebar
+# E.g. Complex Component
+
+## Sidebar
 
 ### **Scalar Definition**
 

package/docs/academy/06-ComponentLibrary/{05-Layout-Components/01-test-toupdate.mdx → 04-LayoutComponent.mdx}

@@ -1,11 +1,8 @@
----
-sidebar_label: 'PHID Field'
-sidebar_position: 1
----
-
 import { Tabs, TabItem } from '@theme/Tabs';
 
-# PHID Field Example
+# E.g. Layout Component 
+
+## PHID Field Example
 
 ### **Scalar Definition**
 

package/docs/academy/06-ComponentLibrary/{06-Fragments/01-test-toupdate.mdx → 05-FragmentsComponent.mdx}

@@ -1,11 +1,8 @@
----
-sidebar_label: 'PHID Field'
-sidebar_position: 1
----
-
 import { Tabs, TabItem } from '@theme/Tabs';
 
-# PHID Field Example
+# E.g. Fragments Component 
+
+## PHID Field Example
 
 ### **Scalar Definition**
 

package/docs/academy/08-Glossary.md

@@ -30,7 +30,9 @@
 - **Actions (Document Actions)** – Typed objects representing an intent to change a document's state, dispatched to reducers, containing an operation type and input data.
 - **API Integration (for Document Models)** – The capability of Document Models to connect with Switchboard API or external APIs, facilitating data exchange between Powerhouse applications and other systems.
 - **Boilerplate (Powerhouse Project)** – The `ph init` command's initial project structure, providing a standard starting point for new Powerhouse packages.
+- **Connect Build** – The output of the `ph connect build` command, which packages a Connect project into a distributable format. This build includes all necessary local/external packages, assets, and styles, and can be previewed locally with `ph connect preview` or deployed.
 - **Data Analysis (with Document Models)** – Leveraging the structured data within Document Models, often via read models, to extract insights, generate reports, and perform analytics on operational and historical data.
+- **Development Environment (Powerhouse)** – A local setup for developing Powerhouse applications, typically initiated with the `ph dev` command. It runs essential backend services like the Powerhouse Switchboard to enable real-time document model processing, code generation, and live updates, separate from the front-end Connect Studio.
 - **Dispatch (in Document Models)** – The act of sending an action (representing an operation) to a document model's reducer to trigger a state update.
 - **Document Model Editors** – An interface or UI to a document model that allows users to create and modify the data captured by the document models.
 - **Document Model Specification** – The formal definition of a document model (state, operations), created in Connect Studio (using GraphQL SDL) and exported (e.g., `.phdm.zip`) for code generation.
@@ -39,6 +41,7 @@
 - **Document Type** – A unique string identifier (e.g., `powerhouse/todolist`) for a Document Model, used by host apps to select the correct editor/logic.
 - **Drive** – A logical container in Powerhouse for storing, organizing, and managing collections of documents.
 - **Drive App (Custom Drive Explorer)** – A UI application, often custom, providing tailored views and interactions with documents in a Drive.
+- **Environments (Powerhouse Environments)** – Pre-defined configurations for a project's Powerhouse dependencies, such as `dev` (development), `prod` (production/latest), and `local`. The Powerhouse CLI (`ph use` command) allows developers to easily switch between these environments to use different versions of packages (e.g., bleeding-edge, stable, or from a local monorepo).
 - **Event History (Append-Only Log)** – An immutable, append-only log where every operation applied to a Powerhouse document is stored as an event. It provides a transparent audit trail and enables features like time travel debugging and state reconstruction.
 - **GraphQL Scalars** – Data types used in Powerhouse document modeling (e.g., `String`, `Int`, `Currency`, `OID` for unique object IDs).
 - **GraphQL Schema Definition Language (SDL) (for Document Models)** – Language used in Connect Studio to define a Document Model's data structure (state) and operations.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@powerhousedao/academy",
-  "version": "2.5.0-dev.10",
+  "version": "2.5.0-dev.12",
   "homepage": "https://powerhouse.academy",
   "repository": {
     "type": "git",

package/sidebars.ts

@@ -68,27 +68,7 @@ const sidebars = {
           link: {
             type: 'generated-index',
           },
-          items: [
-            'academy/MasteryTrack/BuildingUserExperiences/BuildingDocumentEditors',
-            'academy/MasteryTrack/BuildingUserExperiences/ConfiguringDrives',
-            'academy/MasteryTrack/BuildingUserExperiences/BuildingADriveExplorer',
-          ]
-        },
-        {
-          type: 'category',
-          label: 'Document Tools',
-          link: {
-            type: 'generated-index',
-          },
-          items: [{ type: 'autogenerated', dirName: 'academy/02-MasteryTrack/03-BuildingUserExperiences/07-DocumentTools' }]
-        },
-        {
-          type: 'category',
-          label: 'Authorization',
-          link: {
-            type: 'generated-index',
-          },
-          items: [{ type: 'autogenerated', dirName: 'academy/02-MasteryTrack/03-BuildingUserExperiences/08-Authorization' }]
+          items: [{ type: 'autogenerated', dirName: 'academy/02-MasteryTrack/03-BuildingUserExperiences' }]
         },
         {
           type: 'category',
@@ -140,30 +120,10 @@ const sidebars = {
             </a>
           `,
         },
-        {
-          type: 'doc',
-          id: 'academy/ComponentLibrary/BuildingWithScalars',
-        },
-        {
-          type: 'category',
-          label: 'Scalar Components',
-          items: [{type: 'autogenerated', dirName: 'academy/06-ComponentLibrary/03-Scalar-Components'}],
-        },
-        {
-          type: 'category',
-          label: 'Complex Components',
-          items: [{type: 'autogenerated', dirName: 'academy/06-ComponentLibrary/04-Complex-Components'}],
-        },
-        {
-          type: 'category',
-          label: 'Layout Components',
-          items: [{type: 'autogenerated', dirName: 'academy/06-ComponentLibrary/05-Layout-Components'}],
-        },
-        {
-          type: 'category',
-          label: 'Fragments',
-          items: [{type: 'autogenerated', dirName: 'academy/06-ComponentLibrary/06-Fragments'}],
-        },
+        'academy/ComponentLibrary/ScalarComponent',
+        'academy/ComponentLibrary/ComplexComponent',
+        'academy/ComponentLibrary/LayoutComponent',
+        'academy/ComponentLibrary/FragmentsComponent',
       ],
     },
 

package/docs/academy/06-ComponentLibrary/02-BuildingWithScalars.md

@@ -1,54 +0,0 @@
-# Build with Scalars
-
-Scalars are here to help you define custom fields in your document model schema and speed up the development process.
-There are two applications of scalar components in the document model workflow:
-
-1. At the **schema definition** level where you build your schema and write your GraphQL state schema.
-2. At the **frontend / react** level where you import it and place it in your UI to represent the scalar field
-
-## Scalar Definition in the Document Model Schema
-
-As you might know, the document model schema defines the structure of the document and serves as the backbone of the document model. The GraphQL state schema defines how data is captured with the help of types & scalars. When you define a scalar in the document model schema, you are essentially defining a new field that can be used in the document model to capture data.
-
-In the Document Model Editor, you can find all the custom scalar types available in our documentation under the 'Scalars' section.
-
-Insert image of the feature. 
-
-````
-scalar PHID <-- imported from the design system library? not sure
-type MyType {
-  myScalar: PHID
-}   
-````
-
-## React Component Implementation in the Frontend
-
-All of our reusable components are available in the Document-Engineering design system library or package.
-This package comes as a dependency in your project when creating a new document model project.
-````
-import PHIDField from 'document-engineering'
-const reactComponent = () => {
-
-return (
-  <div>
-    <PHIDField
-      fetchOptionsCallback={function Js(){}}
-      fetchSelectedOptionCallback={function Js(){}}
-      label="PHID field"
-      name="phid-field"
-      placeholder="phd:"
-    />
-
-  </div>
-  
-  )
-
-}
-````
-
-## Scalars & Reusable Components
-
-To make your life easier, Powerhouse has defined all useful scalars with a set of reusable code and UI components.
-The reusable components are essentially a set of front-end components based on GraphQL scalars. Powerhouse also has a set of custom scalars that are not part of the GraphQL standard but are specific to the web3 ecosystem.
-
-Read the next chapter to get familiar with our reusable components.