@learnpack/learnpack 5.0.355 → 5.0.358

package/src/creator/README.md

@@ -1,54 +1,66 @@
-# React + TypeScript + Vite
-
-This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
-
-Currently, two official plugins are available:
-
-- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react/README.md) uses [Babel](https://babeljs.io/) for Fast Refresh
-- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
-
-## Expanding the ESLint configuration
-
-If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
-
-```js
-export default tseslint.config({
-  extends: [
-    // Remove ...tseslint.configs.recommended and replace with this
-    ...tseslint.configs.recommendedTypeChecked,
-    // Alternatively, use this for stricter rules
-    ...tseslint.configs.strictTypeChecked,
-    // Optionally, add this for stylistic rules
-    ...tseslint.configs.stylisticTypeChecked,
-  ],
-  languageOptions: {
-    // other options...
-    parserOptions: {
-      project: ["./tsconfig.node.json", "./tsconfig.app.json"],
-      tsconfigRootDir: import.meta.dirname,
-    },
-  },
-})
+# LearnPack Creator
+
+The React + Vite app behind the `/creator` routes: the wizard that collects a course
+brief, and the syllabus editor where the user refines the generated outline before the
+course is created.
+
+It is a separate TypeScript project from the CLI. The root `tsconfig.json` explicitly
+excludes `src/creator`, and this app is ESM (`"type": "module"`) while the CLI is
+CommonJS. Nothing here is compiled by the CLI build.
+
+## ⚠️ Read this before you commit
+
+A PR that changes `src/creator/src/**` **must not** include `src/creatorDist/**`.
+
+`src/creatorDist/` is the compiled output of this app, committed to git because it is
+what the CLI serves at runtime and ships to npm. It is a **release artifact**: it gets
+rebuilt and committed only in the release commit, by `autoUpload.sh` at the repository
+root.
+
+Committing it in a feature PR causes conflicts that cannot be resolved by merging —
+Vite emits content-hashed filenames, so every rebuild rewrites `index.html` and adds a
+differently named asset.
+
+Corollary: **merging a creator change does not deploy it.** It ships when someone
+publishes.
+
+Full rationale in [`docs/creator-bundle.md`](../../docs/creator-bundle.md).
+
+## Commands
+
+Run these from `src/creator/`:
+
+```bash
+npm install          # this app has its own node_modules; the root install does not cover it
+npm run dev          # Vite dev server with HMR
+npm run build        # tsc -b && vite build -> ../creatorDist (not committed, see above)
+npm run watch        # vite build --watch, for testing against a local CLI server
+npm run test         # vitest; this app has its own runner, the root `npm test` does not cover it
+npm run lint         # ESLint
 ```
 
-You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
-
-```js
-// eslint.config.js
-import reactX from "eslint-plugin-react-x"
-import reactDom from "eslint-plugin-react-dom"
-
-export default tseslint.config({
-  plugins: {
-    // Add the react-x and react-dom plugins
-    "react-x": reactX,
-    "react-dom": reactDom,
-  },
-  rules: {
-    // other rules...
-    // Enable its recommended typescript rules
-    ...reactX.configs["recommended-typescript"].rules,
-    ...reactDom.configs.recommended.rules,
-  },
-})
+## Layout
+
 ```
+src/
+  App.tsx                     wizard: brief -> purpose -> duration -> human check
+  components/
+    NotificationListener.tsx  socket.io subscription to a Rigobot completion webhook
+    syllabus/                 syllabus editor and its chat sidebar
+  utils/
+    rigo.ts                   calls to the Rigobot prompting API
+    socket.ts                 socket.io client wrapper
+    store.ts                  zustand store, persisted to localStorage
+  locales/                    i18n resources (en, es)
+```
+
+## How generation works
+
+Course generation is asynchronous. `publicInteractiveCreation` posts to Rigobot with a
+`webhook_url` pointing at the CLI server (`POST /notifications/:id`), and Rigobot answers
+`201` immediately with a pending job. The CLI relays the eventual webhook over socket.io,
+and `NotificationListener` resolves it in the browser.
+
+That means **an HTTP 2xx from Rigobot says nothing about whether generation succeeded**.
+The job can still fail later and arrive over the socket with `status: "ERROR"` and
+`parsed: null`. Any code consuming a notification payload has to handle that.