Monorepo: browser-safe @sysprom/core + Vite viewer on GitHub Pages

.SysProM.json

@@ -4094,6 +4094,51 @@
 				"src/operations/graph-shared.ts,src/operations/graph.ts,src/json-to-md.ts,src/cli/commands/graph.ts,src/cli/commands/json2md.ts"
 			],
 			"type": "change"
+		},
+		{
+			"context": "We want a GitHub Pages-hosted web app for visualising SysProM documents. The single sysprom package cannot be imported by a browser app because the library modules call node:fs, node:path, and node:crypto directly (io.ts, sync.ts, the multi-doc conversions, three speckit ops), and the operations barrel re-exports syncDocumentsOp, dragging node:fs into every barrel import.",
+			"id": "DEC52",
+			"name": "Adopt pnpm workspace monorepo with a browser-safe core and a Vite viewer",
+			"options": [
+				{
+					"description": "Convert to a pnpm workspace; extract a browser-safe @sysprom/core; keep filesystem access in @sysprom/node; preserve the sysprom package via a cli re-export; add an unpublished Vite viewer",
+					"id": "MONO"
+				},
+				{
+					"description": "Keep sysprom as-is; build the viewer in a second repo that imports sysprom from npm",
+					"id": "SEPARATE"
+				},
+				{
+					"description": "Add the viewer as a subpath of the current single package with node:fs polyfills for the browser",
+					"id": "SINGLE"
+				}
+			],
+			"rationale": "A workspace lets the viewer consume core source directly via workspace links with no npm publish lag, and forces the filesystem isolation the library already needs so domain logic is isomorphic behind a storage boundary. A separate repo adds a publish lag for every core change the UI needs. A single-package browser entry needs node:fs and node:path polyfills rather than fixing the boundary. pnpm and Turbo are already in use, so the workspace conversion cost is low; all packages ship together, so unified versioning applies.",
+			"selected": "MONO",
+			"type": "decision"
+		},
+		{
+			"id": "CHG50",
+			"lifecycle": {
+				"introduced": true
+			},
+			"name": "Convert to monorepo; extract browser-safe core; add Vite viewer",
+			"scope": [
+				"packages/core",
+				"packages/node",
+				"packages/cli",
+				"packages/mcp",
+				"packages/web",
+				"build",
+				"ci"
+			],
+			"type": "change"
+		},
+		{
+			"description": "The published sysprom package contract is preserved across the monorepo split: the sysprom, spm, and sysprom-mcp CLI binaries continue to install and run, and every name currently importable from sysprom remains exported with its existing signature. Existing Node consumers see no change.",
+			"id": "INV33",
+			"name": "Published Package Contract Stability",
+			"type": "invariant"
 		}
 	],
 	"relationships": [
@@ -5266,6 +5311,16 @@
 			"from": "CHG49",
 			"to": "DEC51",
 			"type": "implements"
+		},
+		{
+			"from": "CHG50",
+			"to": "DEC52",
+			"type": "implements"
+		},
+		{
+			"from": "DEC52",
+			"to": "INV33",
+			"type": "must_preserve"
 		}
 	]
 }

.SysProM/CHANGES.md

@@ -826,3 +826,20 @@ Scope:
 Scope:
 - src/operations/graph-shared.ts,src/operations/graph.ts,src/json-to-md.ts,src/cli/commands/graph.ts,src/cli/commands/json2md.ts
 
+### CHG50 — Convert to monorepo; extract browser-safe core; add Vite viewer
+
+- Implements: [DEC52](./DECISIONS.md#dec52--adopt-pnpm-workspace-monorepo-with-a-browser-safe-core-and-a-vite-viewer)
+
+Scope:
+- packages/core
+- packages/node
+- packages/cli
+- packages/mcp
+- packages/web
+- build
+- ci
+
+#### Lifecycle
+
+- [x] introduced
+

.SysProM/DECISIONS.md

@@ -1006,3 +1006,18 @@ Chosen: OPT-A
 
 Rationale: Anchor-based links provide the best UX for embedded diagrams since clicking navigates directly to the node definition. External reference links serve standalone use cases.
 
+### DEC52 — Adopt pnpm workspace monorepo with a browser-safe core and a Vite viewer
+
+- Must preserve: [INV33](./INVARIANTS.md#inv33--published-package-contract-stability)
+
+Context: We want a GitHub Pages-hosted web app for visualising SysProM documents. The single sysprom package cannot be imported by a browser app because the library modules call node:fs, node:path, and node:crypto directly (io.ts, sync.ts, the multi-doc conversions, three speckit ops), and the operations barrel re-exports syncDocumentsOp, dragging node:fs into every barrel import.
+
+Options:
+- MONO: Convert to a pnpm workspace; extract a browser-safe @sysprom/core; keep filesystem access in @sysprom/node; preserve the sysprom package via a cli re-export; add an unpublished Vite viewer
+- SEPARATE: Keep sysprom as-is; build the viewer in a second repo that imports sysprom from npm
+- SINGLE: Add the viewer as a subpath of the current single package with node:fs polyfills for the browser
+
+Chosen: MONO
+
+Rationale: A workspace lets the viewer consume core source directly via workspace links with no npm publish lag, and forces the filesystem isolation the library already needs so domain logic is isomorphic behind a storage boundary. A separate repo adds a publish lag for every core change the UI needs. A single-package browser entry needs node:fs and node:path polyfills rather than fixing the boundary. pnpm and Turbo are already in use, so the workspace conversion cost is low; all packages ship together, so unified versioning applies.
+

.SysProM/INVARIANTS.md

@@ -153,6 +153,10 @@ Setting a node to status: retired via updateNode must report all active nodes th
 
 When both JSON and Markdown representations of a SysProM document exist, mutations via the CLI must automatically keep them in sync. Users should not need to manually run json2md or md2json after every change.
 
+### INV33 — Published Package Contract Stability
+
+The published sysprom package contract is preserved across the monorepo split: the sysprom, spm, and sysprom-mcp CLI binaries continue to install and run, and every name currently importable from sysprom remains exported with its existing signature. Existing Node consumers see no change.
+
 ## Principles
 
 ### PRIN1 — Separate What From Why From How

.github/workflows/ci.yml

@@ -33,8 +33,8 @@ jobs:
             turbo-quality-${{ runner.os }}-
       - run: npx turbo run _typecheck _test
 
-  docs:
-    name: Docs
+  site:
+    name: Build site
     runs-on: ubuntu-latest
     needs: quality
     steps:
@@ -47,19 +47,25 @@ jobs:
       - uses: actions/cache@v5
         with:
           path: .turbo
-          key: turbo-docs-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}-${{ github.sha }}
+          key: turbo-site-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}-${{ github.sha }}
           restore-keys: |
-            turbo-docs-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}-
-            turbo-docs-${{ runner.os }}-
+            turbo-site-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}-
+            turbo-site-${{ runner.os }}-
+      # Web app at the site root (builds @sysprom/core first via the workspace dep)
+      - run: npx turbo run build --filter=web
+      # TypeDoc HTML API docs -> site/
       - run: npx turbo run _docs:cli _docs:api:html
+      # Serve docs under /docs alongside the viewer at /
+      - name: Place docs under the web build
+        run: cp -r site packages/web/dist/docs
       - uses: actions/upload-pages-artifact@v4
         with:
-          path: site/
+          path: packages/web/dist
 
   pages:
     name: Deploy Pages
     if: github.ref == 'refs/heads/main' && github.event_name == 'push'
-    needs: docs
+    needs: site
     runs-on: ubuntu-latest
     environment:
       name: github-pages

eslint.config.ts

@@ -230,7 +230,11 @@ export default defineConfig(
 		languageOptions: {
 			parserOptions: {
 				projectService: {
-					allowDefaultProject: ["eslint.config.ts", "scripts/*.ts"],
+					allowDefaultProject: [
+						"eslint.config.ts",
+						"tsdown.config.ts",
+						"scripts/*.ts",
+					],
 				},
 				tsconfigRootDir: import.meta.dirname,
 			},
@@ -256,7 +260,7 @@ export default defineConfig(
 		},
 	},
 	{
-		files: ["src/**/*.ts"],
+		files: ["src/**/*.ts", "packages/core/src/**/*.ts"],
 		rules: {
 			"@typescript-eslint/no-unnecessary-condition": "off",
 			"sonarjs/cognitive-complexity": "off",
@@ -271,7 +275,7 @@ export default defineConfig(
 		},
 	},
 	{
-		files: ["tests/**/*.ts"],
+		files: ["tests/**/*.ts", "packages/core/tests/**/*.ts"],
 		rules: {
 			"@typescript-eslint/consistent-type-assertions": [
 				"error",
@@ -310,7 +314,7 @@ export default defineConfig(
 	{
 		ignores: [
 			".claude/worktrees/**",
-			"dist/",
+			"**/dist/",
 			"node_modules/",
 			"docs/",
 			"commitlint.config.ts",

package.json

@@ -20,23 +20,23 @@
 	],
 	"packageManager": "pnpm@10.32.1",
 	"type": "module",
-	"main": "./dist/src/index.js",
-	"types": "./dist/src/index.d.ts",
+	"main": "./dist/index.mjs",
+	"types": "./dist/index.d.mts",
 	"exports": {
 		".": {
-			"types": "./dist/src/index.d.ts",
-			"import": "./dist/src/index.js"
+			"types": "./dist/index.d.mts",
+			"import": "./dist/index.mjs"
 		}
 	},
 	"files": [
-		"dist/src/**/*.js",
-		"dist/src/**/*.d.ts",
+		"dist/**/*.mjs",
+		"dist/**/*.d.mts",
 		"schema.json"
 	],
 	"bin": {
-		"sysprom": "dist/src/cli/index.js",
-		"spm": "dist/src/cli/index.js",
-		"sysprom-mcp": "dist/src/mcp/index.js"
+		"sysprom": "dist/cli/index.mjs",
+		"spm": "dist/cli/index.mjs",
+		"sysprom-mcp": "dist/mcp/index.mjs"
 	},
 	"scripts": {
 		"build": "turbo run _build",
@@ -51,7 +51,7 @@
 		"spm": "tsx src/cli/index.ts",
 		"_lint": "eslint --cache .",
 		"_typecheck": "tsc --noEmit",
-		"_compile": "tsc",
+		"_compile": "tsdown",
 		"_schema": "tsx src/generate-schema.ts",
 		"_test": "tsx --test tests/*.test.ts",
 		"_test:coverage": "c8 --src src --exclude 'src/cli/**' --exclude 'src/generate-schema.ts' tsx --test tests/*.test.ts",
@@ -87,6 +87,7 @@
 		"@semantic-release/changelog": "6.0.3",
 		"@semantic-release/exec": "7.1.0",
 		"@semantic-release/git": "10.0.1",
+		"@sysprom/core": "workspace:*",
 		"@types/node": "25.5.0",
 		"c8": "11.0.0",
 		"conventional-changelog-conventionalcommits": "9.3.0",
@@ -100,12 +101,13 @@
 		"lint-staged": "16.4.0",
 		"prettier": "3.8.1",
 		"semantic-release": "25.0.3",
+		"tsdown": "0.22.3",
 		"tsx": "4.21.0",
 		"turbo": "2.8.20",
 		"typedoc": "0.28.18",
 		"typedoc-plugin-markdown": "4.11.0",
 		"typedoc-plugin-zod": "1.4.3",
-		"typescript": "6.0.2",
+		"typescript": "6.0.3",
 		"typescript-eslint": "8.58.0"
 	}
 }

packages/core/package.json

@@ -0,0 +1,42 @@
+{
+	"name": "@sysprom/core",
+	"version": "0.0.0",
+	"private": true,
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		},
+		"./operations/index.js": {
+			"types": "./dist/operations/index.d.ts",
+			"import": "./dist/operations/index.js"
+		},
+		"./operations/graph-shared.js": {
+			"types": "./dist/operations/graph-shared.d.ts",
+			"import": "./dist/operations/graph-shared.js"
+		},
+		"./speckit/plan.js": {
+			"types": "./dist/speckit/plan.d.ts",
+			"import": "./dist/speckit/plan.js"
+		}
+	},
+	"files": [
+		"dist/**"
+	],
+	"scripts": {
+		"build": "tsc -p tsconfig.build.json",
+		"typecheck": "tsc --noEmit",
+		"test": "tsx --test tests/*.test.ts"
+	},
+	"dependencies": {
+		"zod": "4.3.6"
+	},
+	"devDependencies": {
+		"@types/node": "25.5.0",
+		"tsx": "4.21.0",
+		"typescript": "6.0.3"
+	}
+}