@powerhousedao/academy 3.3.0-dev.7 → 3.3.0-dev.9

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## 3.3.0-dev.9 (2025-07-10)
+
+### 🩹 Fixes
+
+- force release ([8185a3b37](https://github.com/powerhouse-inc/powerhouse/commit/8185a3b37))
+
+### ❤️ Thank You
+
+- Guillermo Puente @gpuente
+
+## 3.3.0-dev.8 (2025-07-10)
+
+This was a version bump only for @powerhousedao/academy to align it with other projects, there were no code changes.
+
 ## 3.3.0-dev.7 (2025-07-10)
 
 This was a version bump only for @powerhousedao/academy to align it with other projects, there were no code changes.

package/docs/academy/04-APIReferences/05-PHDocumentMigrationGuide.md

@@ -0,0 +1,338 @@
+# PHDocument Migration Guide (v3.3.0)
+
+:::tip
+This guide covers the **breaking changes** introduced in Powerhouse v3.3.0 related to PHDocument structure changes. If you're upgrading from v3.2.0 or earlier, **this migration is required** and document models must be regenerated.
+:::
+
+## Overview
+
+Version 3.3.0 introduced a significant refactor of the `PHDocument` structure that consolidates document metadata into a `header` field. This change enables signed and unsigned documents with cryptographic verification capabilities, but requires updating all code that accesses document properties.
+
+## What Changed
+
+### Document Structure Refactor
+
+The most significant change is the consolidation of document metadata into a `header` field. Previously, document properties were scattered at the root level of the document object.
+
+**Before (v3.2.0 and earlier):**
+```javascript
+const document = {
+  id: "doc-123",
+  created: "2023-01-01T00:00:00.000Z",
+  lastModified: "2023-01-01T12:00:00.000Z",
+  revision: 5,
+  documentType: "powerhouse/todolist",
+  name: "My Todo List",
+  slug: "my-todo-list",
+  // ... other properties
+}
+```
+
+**After (v3.3.0):**
+```javascript
+const document = {
+  header: {
+    id: "doc-123",
+    createdAtUtcIso: "2023-01-01T00:00:00.000Z",
+    lastModifiedAtUtcIso: "2023-01-01T12:00:00.000Z",
+    revision: { global: 5, local: 0 },
+    documentType: "powerhouse/todolist",
+    name: "My Todo List",
+    slug: "my-todo-list",
+    branch: "main",
+    sig: { nonce: "", publicKey: {} },
+    meta: {}
+  },
+  // ... other properties
+}
+```
+
+## Complete Property Migration Map
+
+| **Old Property** | **New Property** | **Additional Changes** |
+|------------------|------------------|------------------------|
+| `document.id` | `document.header.id` | Now an Ed25519 signature for signed documents |
+| `document.created` | `document.header.createdAtUtcIso` | **Renamed** to include UTC ISO specification |
+| `document.lastModified` | `document.header.lastModifiedAtUtcIso` | **Renamed** to include UTC ISO specification |
+| `document.revision` | `document.header.revision` | Now an **object** with scope keys (e.g., `{ global: 5, local: 0 }`) |
+| `document.documentType` | `document.header.documentType` | No additional changes |
+| `document.name` | `document.header.name` | No additional changes |
+| `document.slug` | `document.header.slug` | No additional changes |
+| `document.branch` | `document.header.branch` | Now explicitly included |
+| `document.meta` | `document.header.meta` | Now explicitly included |
+| N/A | `document.header.sig` | **New** - Signature information for document verification |
+
+## Step-by-Step Migration Guide
+
+### Step 1: Update Document Property Access
+
+Replace all instances of direct property access with header-based access:
+
+<details>
+<summary>**Common Property Access Patterns**</summary>
+
+**Document ID Access:**
+```javascript
+// Before
+const documentId = document.id;
+
+// After
+const documentId = document.header.id;
+```
+
+**Document Name Access:**
+```javascript
+// Before
+const documentName = document.name;
+
+// After
+const documentName = document.header.name;
+```
+
+**Document Type Access:**
+```javascript
+// Before
+const docType = document.documentType;
+
+// After
+const docType = document.header.documentType;
+```
+
+**Timestamp Access:**
+```javascript
+// Before
+const created = document.created;
+const lastModified = document.lastModified;
+
+// After
+const created = document.header.createdAtUtcIso;
+const lastModified = document.header.lastModifiedAtUtcIso;
+```
+
+**Revision Access:**
+```javascript
+// Before
+const revision = document.revision; // Was a number
+
+// After
+const globalRevision = document.header.revision.global; // Now an object
+const localRevision = document.header.revision.local;
+// Or get all revisions
+const allRevisions = document.header.revision; // { global: 5, local: 0, ... }
+```
+
+</details>
+
+### Step 2: Update Component Code
+
+**React Components:**
+
+<details>
+<summary>**Example: Document List Component**</summary>
+
+```jsx
+// Before
+function DocumentList({ documents }) {
+  return (
+    <div>
+      {documents.map(doc => (
+        <div key={doc.id} className="document-item">
+          <h3>{doc.name}</h3>
+          <p>Type: {doc.documentType}</p>
+          <p>Last modified: {new Date(doc.lastModified).toLocaleDateString()}</p>
+          <p>Revision: {doc.revision}</p>
+        </div>
+      ))}
+    </div>
+  );
+}
+
+// After
+function DocumentList({ documents }) {
+  return (
+    <div>
+      {documents.map(doc => (
+        <div key={doc.header.id} className="document-item">
+          <h3>{doc.header.name}</h3>
+          <p>Type: {doc.header.documentType}</p>
+          <p>Last modified: {new Date(doc.header.lastModifiedAtUtcIso).toLocaleDateString()}</p>
+          <p>Global Revision: {doc.header.revision.global}</p>
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+</details>
+
+### Step 3: Update Type Definitions
+
+If you're using TypeScript, update your type definitions:
+
+<details>
+<summary>**TypeScript Interface Updates**</summary>
+
+```typescript
+// Before
+interface MyDocument {
+  id: string;
+  name: string;
+  documentType: string;
+  created: string;
+  lastModified: string;
+  revision: number;
+  // ... other properties
+}
+
+// After
+interface MyDocument {
+  header: {
+    id: string;
+    name: string;
+    documentType: string;
+    createdAtUtcIso: string;
+    lastModifiedAtUtcIso: string;
+    revision: {
+      [scope: string]: number;
+    };
+    slug: string;
+    branch: string;
+    sig: {
+      nonce: string;
+      publicKey: any;
+    };
+    meta?: {
+      preferredEditor?: string;
+    };
+  };
+  // ... other properties
+}
+```
+
+</details>
+
+### Step 4: Database Queries and APIs Compatibility
+
+<details>
+<summary>**GraphQL Query Compatibility**</summary>
+
+**GraphQL Queries:**
+```graphql
+# Your existing queries continue to work unchanged
+query GetDocument($id: ID!) {
+  document(id: $id) {
+    id              # Still works due to response transformation
+    name            # Still works due to response transformation
+    documentType    # Still works due to response transformation
+    created         # Still works due to response transformation
+    lastModified    # Still works due to response transformation
+    revision        # Still works due to response transformation
+  }
+}
+```
+
+:::tip
+**GraphQL Backward Compatibility:** The GraphQL API maintains backward compatibility through response transformation. Your existing queries will continue to work without changes. However, when working with the raw document objects in your application code, you'll need to use the new header structure.
+:::
+
+</details>
+
+
+
+
+
+## Common Migration Issues and Solutions
+
+### Issue 1: Undefined Property Errors
+
+**Problem:** Getting `undefined` when accessing document properties.
+
+**Solution:** Update property access to use the header structure:
+
+```javascript
+// This will be undefined after migration
+const name = document.name;
+
+// Use this instead
+const name = document.header.name;
+```
+
+### Issue 2: Revision Type Mismatch
+
+**Problem:** Code expecting revision to be a number but getting an object.
+
+**Solution:** Update revision access to specify the scope:
+
+```javascript
+// Before - revision was a number
+if (document.revision > 5) { ... }
+
+// After - revision is an object with scope keys
+if (document.header.revision.global > 5) { ... }
+```
+
+### Issue 3: Date Format Changes
+
+**Problem:** Date parsing issues due to property name changes.
+
+**Solution:** Update timestamp property names:
+
+```javascript
+// Before
+const createdDate = new Date(document.created);
+const modifiedDate = new Date(document.lastModified);
+
+// After
+const createdDate = new Date(document.header.createdAtUtcIso);
+const modifiedDate = new Date(document.header.lastModifiedAtUtcIso);
+```
+
+## Testing Your Migration
+
+### Automated Testing
+
+Create tests to verify your migration:
+
+<details>
+<summary>**Migration Test Examples**</summary>
+
+```javascript
+// Test document property access
+describe('Document Migration', () => {
+  it('should access document properties correctly', () => {
+    const mockDocument = {
+      header: {
+        id: 'test-id',
+        name: 'Test Document',
+        documentType: 'powerhouse/test',
+        createdAtUtcIso: '2023-01-01T00:00:00.000Z',
+        lastModifiedAtUtcIso: '2023-01-01T12:00:00.000Z',
+        revision: { global: 5, local: 0 },
+        // ... other header properties
+      },
+      // ... other document properties
+    };
+
+    // Test property access
+    expect(mockDocument.header.id).toBe('test-id');
+    expect(mockDocument.header.name).toBe('Test Document');
+    expect(mockDocument.header.revision.global).toBe(5);
+  });
+});
+```
+
+</details>
+
+
+
+## Related Documentation
+
+- [PHDocument Architecture](../05-Architecture/PHDocument.md)
+- [Document Model Creation](../02-MasteryTrack/DocumentModelCreation/WhatIsADocumentModel.md)
+- [GraphQL API Reference](./02-ReactorAPI.md)
+- [React Hooks](./01-ReactHooks.md)
+
+---
+
+*This migration guide covers the major changes in v3.3.0. For additional technical details, refer to the [RELEASE-NOTES.md](https://github.com/powerhouse-dao/powerhouse/blob/main/RELEASE-NOTES.md) in the main repository.* 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@powerhousedao/academy",
-  "version": "3.3.0-dev.7",
+  "version": "3.3.0-dev.9",
   "homepage": "https://powerhouse.academy",
   "repository": {
     "type": "git",

package/sidebars.ts

@@ -1,5 +1,3 @@
-import type { SidebarsConfig } from '@docusaurus/plugin-content-docs';
-
 /**
  * Creating a sidebar enables you to:
  - create an ordered group of docs
@@ -14,101 +12,121 @@ const sidebars = {
   // By default, Docusaurus generates a sidebar from the docs folder structure
   academySidebar: [
     {
-      type: 'category',
-      label: 'Get started',
+      type: "category",
+      label: "Get started",
       link: {
-        type: 'doc',
-        id: 'academy/GetStarted/home',
+        type: "doc",
+        id: "academy/GetStarted/home",
       },
       items: [
-        'academy/GetStarted/ExploreDemoPackage',
-        'academy/GetStarted/CreateNewPowerhouseProject',
-        'academy/GetStarted/DefineToDoListDocumentModel',
-        'academy/GetStarted/ImplementOperationReducers',
-        'academy/GetStarted/BuildToDoListEditor',
+        "academy/GetStarted/ExploreDemoPackage",
+        "academy/GetStarted/CreateNewPowerhouseProject",
+        "academy/GetStarted/DefineToDoListDocumentModel",
+        "academy/GetStarted/ImplementOperationReducers",
+        "academy/GetStarted/BuildToDoListEditor",
       ],
     },
     {
-      type: 'category',
-      label: 'Mastery track',
+      type: "category",
+      label: "Mastery track",
       items: [
         {
-          type: 'category',
-          label: 'Builder environment',
+          type: "category",
+          label: "Builder environment",
           link: {
-            type: 'doc',
-            id: 'academy/MasteryTrack/BuilderEnvironment/Prerequisites'
+            type: "doc",
+            id: "academy/MasteryTrack/BuilderEnvironment/Prerequisites",
           },
           items: [
-            'academy/MasteryTrack/BuilderEnvironment/Prerequisites',
-            'academy/MasteryTrack/BuilderEnvironment/StandardDocumentModelWorkflow',
-            'academy/MasteryTrack/BuilderEnvironment/BuilderTools',
-          ]
+            "academy/MasteryTrack/BuilderEnvironment/Prerequisites",
+            "academy/MasteryTrack/BuilderEnvironment/StandardDocumentModelWorkflow",
+            "academy/MasteryTrack/BuilderEnvironment/BuilderTools",
+          ],
         },
         {
-          type: 'category',
-          label: 'Document model creation',
+          type: "category",
+          label: "Document model creation",
           link: {
-            type: 'generated-index',
+            type: "generated-index",
           },
           items: [
-            'academy/MasteryTrack/DocumentModelCreation/WhatIsADocumentModel',
-            'academy/MasteryTrack/DocumentModelCreation/SpecifyTheStateSchema',
-            'academy/MasteryTrack/DocumentModelCreation/SpecifyDocumentOperations',
-            'academy/MasteryTrack/DocumentModelCreation/UseTheDocumentModelGenerator',
-            'academy/MasteryTrack/DocumentModelCreation/ImplementDocumentReducers',
-            'academy/MasteryTrack/DocumentModelCreation/ImplementDocumentModelTests',
-            'academy/MasteryTrack/DocumentModelCreation/ExampleToDoListRepository',
-          ]
+            "academy/MasteryTrack/DocumentModelCreation/WhatIsADocumentModel",
+            "academy/MasteryTrack/DocumentModelCreation/SpecifyTheStateSchema",
+            "academy/MasteryTrack/DocumentModelCreation/SpecifyDocumentOperations",
+            "academy/MasteryTrack/DocumentModelCreation/UseTheDocumentModelGenerator",
+            "academy/MasteryTrack/DocumentModelCreation/ImplementDocumentReducers",
+            "academy/MasteryTrack/DocumentModelCreation/ImplementDocumentModelTests",
+            "academy/MasteryTrack/DocumentModelCreation/ExampleToDoListRepository",
+          ],
         },
         {
-          type: 'category',
-          label: 'Building user experiences',
+          type: "category",
+          label: "Building user experiences",
           link: {
-            type: 'generated-index',
+            type: "generated-index",
           },
-          items: [{ type: 'autogenerated', dirName: 'academy/02-MasteryTrack/03-BuildingUserExperiences' }]
+          items: [
+            {
+              type: "autogenerated",
+              dirName: "academy/02-MasteryTrack/03-BuildingUserExperiences",
+            },
+          ],
         },
         {
-          type: 'category',
-          label: 'Work with data',
+          type: "category",
+          label: "Work with data",
           link: {
-            type: 'generated-index',
+            type: "generated-index",
           },
-          items: [{type: 'autogenerated', dirName: 'academy/02-MasteryTrack/04-WorkWithData'}]
+          items: [
+            {
+              type: "autogenerated",
+              dirName: "academy/02-MasteryTrack/04-WorkWithData",
+            },
+          ],
         },
         {
-          type: 'category',
-          label: 'Launch',
+          type: "category",
+          label: "Launch",
           link: {
-            type: 'generated-index',
+            type: "generated-index",
           },
-          items: [{type: 'autogenerated', dirName: 'academy/02-MasteryTrack/05-Launch'}]
-        }
+          items: [
+            {
+              type: "autogenerated",
+              dirName: "academy/02-MasteryTrack/05-Launch",
+            },
+          ],
+        },
       ],
     },
     {
-      type: 'category',
-      label: 'Example usecases',
-      items: [{ type: 'autogenerated', dirName: 'academy/03-ExampleUsecases' }],
+      type: "category",
+      label: "Example usecases",
+      items: [{ type: "autogenerated", dirName: "academy/03-ExampleUsecases" }],
     },
     {
-      type: 'category',
-      label: 'API References',
-      items: [{ type: 'autogenerated', dirName: 'academy/04-APIReferences' }],
+      type: "category",
+      label: "API References",
+      items: [
+        "academy/APIReferences/PowerhouseCLI",
+        "academy/APIReferences/ReactHooks",
+        "academy/APIReferences/OperationalDatabase",
+        "academy/APIReferences/PHDocumentMigrationGuide",
+      ],
     },
 
     // Manually define the Component Library category
     {
-      type: 'category',
-      label: 'Component library',
+      type: "category",
+      label: "Component library",
       items: [
         {
-          type: 'doc',
-          id: 'academy/ComponentLibrary/DocumentEngineering',
+          type: "doc",
+          id: "academy/ComponentLibrary/DocumentEngineering",
         },
         {
-          type: 'html',
+          type: "html",
           value: `
             <a class="menu__link" href="https://storybook.powerhouse.academy/" target="_blank" rel="noopener" style="display: flex; align-items: center; justify-content: space-between; font-weight: 500; text-decoration: none;">
               <span style="display: flex; align-items: center; gap: 6px;">
@@ -119,21 +137,21 @@ const sidebars = {
             </a>
           `,
         },
-        'academy/ComponentLibrary/CreateCustomScalars',
-        'academy/ComponentLibrary/IntegrateIntoAReactComponent',
+        "academy/ComponentLibrary/CreateCustomScalars",
+        "academy/ComponentLibrary/IntegrateIntoAReactComponent",
       ],
     },
 
     // Everything after Component Library is still autogenerated
     {
-      type: 'category',
-      label: 'Architecture',
-      items: [{ type: 'autogenerated', dirName: 'academy/05-Architecture' }],
+      type: "category",
+      label: "Architecture",
+      items: [{ type: "autogenerated", dirName: "academy/05-Architecture" }],
     },
-    { type: 'doc', id: 'academy/Cookbook', label: 'Cookbook' },
-    { type: 'doc', id: 'academy/Glossary', label: 'Glossary' },
+    { type: "doc", id: "academy/Cookbook", label: "Cookbook" },
+    { type: "doc", id: "academy/Glossary", label: "Glossary" },
     // ...add more as needed
   ],
 };
 
-export default sidebars;
+export default sidebars;