@ibgib/space-gib 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,31 @@
+# @ibgib/space-gib changelog
+
+_note: as you implement features/fixes/etc., please document them here under the "Working Version" section. These will be moved to a concrete version number during the next publish._
+
+## Working Version
+
+* feat: serve-gib microframework and core architecture
+  * established dual-target architecture for browser SPA client and Node.js server.
+  * implemented the `serve-gib` microframework with pipeline-based orchestration and async handlers.
+  * implemented `ServeGib_V1` with robust `try..catch..finally` logging and error handling.
+  * implemented `ServeGibHandlerBase` "pit of success" plumbing for automated matching and param parsing.
+  * established hierarchical folder-based handler organization mirroring URL paths (e.g., `api/ibgib/`).
+  * migrated all routing logic to modular, single-file handlers.
+* feat: space-service and API endpoints
+  * implemented `SpaceService` with initial filesystem-backed storage.
+  * implemented `GET /api/health` liveness probe.
+  * implemented `GET /api/ibgib/:addr` and `GET /api/ibgib/graph/:addr` for graph retrieval.
+  * implemented `POST /api/keystone` for genesis and evolution turns with keystone-specific validation logic.
+* feat: security hardening and path validation
+  * implemented `path-helper.mts` with hardened regex-based whitelists and blacklists.
+  * added `isSafePath` to block directory traversal, null bytes, redundant slashes, and dot-file access.
+  * enforced `MAX_PATH_LENGTH` (2048 chars) to prevent DoS-style payload attacks.
+  * integrated deep ibGib address validation using `validateIbGibAddr` from `ts-gib`.
+  * enforced V1 address schema (at most one dot in `gib` segment).
+* feat: build and test infrastructure
+  * refactored `BuildSpaceGib` to use parallel, color-coded, and stateful error-tagged logging.
+  * established `tsconfig.server.json` and `tsconfig.test.json` for isolated environment builds.
+  * integrated `respec-gib` testing framework with a comprehensive suite for path validation.
+  * added `test:space-gib` orchestration to the monorepo root.
+* feat: client-side components
+  * implemented `keystone-creator` component for initiating identity keystones.

package/Dockerfile

@@ -0,0 +1,14 @@
+FROM node:22-alpine
+WORKDIR /app
+
+# The server is bundled into a single zero-dependency ESM file via esbuild
+COPY dist/server ./server
+
+# Client SPA (served as static files by the node server)
+COPY dist/client ./client
+
+ENV PORT=3000
+ENV DATA_DIR=/data/ibgib-space
+
+EXPOSE 3000
+CMD ["node", "server/server.mjs"]

package/IMPLEMENTATION.md

@@ -0,0 +1,484 @@
+# space-gib — Implementation Spec
+
+`space-gib` is the ibgib storage and identity provider service, deployed as a Docker
+container alongside `blank-gib`. It is a single container that serves both:
+1. A **Node.js API server** wrapping `NodeFilesystemSpace_V1` (ibgib storage + keystone ops)
+2. A **browser SPA** (four-panel ibgib web app, client-side UI)
+
+Published to: `https://ibgib.space`
+
+---
+
+## Core Design Decisions
+
+### Keystone-as-Scope (not Keystone-as-Identity)
+Keystones here are **authorization contexts**, not identity credentials (identity comes
+later and is a specialization of this pattern). Any ibgib write requires solving the
+current context keystone. The keystone evolution history IS the audit log of what was
+written under that scope.
+
+- **Public reads**: all ibgibs are publicly readable — no auth required for GET
+- **Keyed writes**: all mutations (put ibgib, evolve keystone) require a valid keystone evolution proof
+- **Nested scopes**: keystones can have child keystones. Parent must be evolved to
+  create a child. Child has `parentTjpGib` in its `data` (soft-link, not rel8n).
+  Operating within child scope does NOT require parent secrets.
+
+### Manifest Ibgib Pattern
+Content is NOT added to a scope directly. The flow is:
+1. Create content ibgib(s) + their DNA/dependency graph (existing ibgib machinery)
+2. **Server creates a manifest ibgib** listing the dependency graph addresses
+3. Context keystone is evolved with `claim.target = manifestIbGibAddr`
+4. Only then are the content ibgibs stored in the space
+
+The keystone chain is therefore an audit log of manifest addresses — each frame
+authorizes exactly one set of content additions.
+
+### Address Conventions
+- Full ibgib address `ib^gib` is used everywhere (NOT just `tjpGib`)
+- `tjpGib` is a reference convenience inside keystones and other ibgibs (stable timeline ID), not a full address
+- URL-encode the `^` delimiter in route params: `ib%5Egib`
+- Example full addr: `comment abc123%5E789def`
+- **Fast TJP Extraction**: Use `getGibInfo` from `@ibgib/ts-gib/src/V1/transforms/transform-helper.mts` to efficiently extract `tjpGib` for routing and path mapping.
+
+### Storage Backend
+`NodeFilesystemSpace_V1` from `@ibgib/core-gib`. Known pain point: filesystem
+path length limits (255 char max). The space has built-in `mitigateLongPaths` logic.
+Data volume mounted at `/data/ibgib-space` inside the container.
+
+---
+
+## Multitenant Architecture: Keystone-as-Domain
+
+`space-gib` implements a horizontal scaling, multitenant architecture where the **Keystone** is the primary mechanism for circumscribing "Digital Private Property."
+
+### Domain Boundaries & Isolation
+*   **The Keystone is the Domain**: A "user" (human, org, or agent) is represented by a top-level keystone. This keystone acts as the boundary of a secure domain.
+*   **Composite Multitenancy**: Subscoped keystones create nested domains, allowing for independently evolving security contexts within a larger organization or project.
+*   **Physical Space Isolation**: Each top-level domain is isolated into its own **self-contained physical space** on the server's filesystem.
+*   **Bootstrap-per-Domain**: Every isolated domain has its own "Zero Space" and `bootstrap^gib`. This ensures that a domain is a completely portable, independent unit of the ibGib graph.
+
+### Deterministic Pathing & Scaling
+To achieve horizontal scaling and combat OS path limits, physical storage paths are derived deterministically from the keystone's `tjpGib`:
+*   **Deterministic Mapping**: The relationship between a Domain (Identity) and its Physical Location is inherent in its `tjpGib`. No central registry or lookup database is required for V1 (Stateless Sharding).
+*   **Path Nesting & Balancing**: To prevent filesystem performance degradation, paths use substrings of the `tjpGib` for distribution:
+    *   **Git-Style Fan-out**: Substrings are applied at each level to balance OS folders (e.g., `/[tjp_sub1]/[tjp_sub2]/[child_tjp_sub1]/...`).
+    *   **Collision Resistance**: Substrings should be long enough (e.g., 8-12 chars) to avoid collisions while staying within path length limits.
+*   **Independent Parallelism**: The `lockSpace` mechanism is domain-specific. Updates to `User A` never contend for locks with `User B`, allowing for massive concurrent throughput across different domains.
+
+### Security & Visibility
+*   **Public Keystones**: Keystones are considered publicly visible records.
+*   **Secret Strength**: Security depends on the strength of the keystone's secret/passphrase (similar to BIP-39 mnemonic phrases in cryptowallets).
+*   **Auditability**: The keystone evolution chain within a domain provides a complete, immutable audit log of all authorized content manifest additions for that property boundary.
+
+### Identity: Aggregate & Checkpoint Details
+To manage identity metadata without bloating every frame or requiring external ibGibs:
+-   **`checkpointDetails`**: Every X frames, a "checkpoint" is written into the keystone's `frameDetails`.
+-   **Rehydration**: To resolve the current identity metadata (e.g., username), the system walks back from the tip to the nearest checkpoint or genesis, then replays forward while aggregating the state using a **Last-Write-Wins** strategy.
+-   **Aggregate State**: This allows for evolving metadata (email, display name) while maintaining a verifiable, audit-friendly identity timeline.
+
+### Sync Sagas: Temp & Durable Spaces
+The synchronization engine (Sync Saga) handles multi-device consistency using a "Commit Phase":
+-   **Temp Space**: Content is initially uploaded/created in an ephemeral `TempSpace`. This allows for long-running transfers without locking the primary domain.
+-   **Durable Space**: The "real" persistent storage.
+-   **Atomic Commit**: Once the content manifest is validated and stored in `TempSpace`, the system should lock the keystone context, evolves the keystone, and performs a straight-forward copy from `Temp` to `Durable`. Current implementation does not support identity correctly, only fully passes tests with some concrete implementations without identity.
+  * todo: incorporate sync engine with space-gib.
+
+### Near-Term Goal: Self-Contained Multitenancy
+Our immediate priority is establishing the V1 multitenant foundation:
+1.  **API Scoping**: Hit an endpoint like `PUT /api/keystone/evolve/:addr`.
+2.  **Domain Resolution**: ServeGib_V1 extracts `tjpGib` and calculates `domainRootPath`.
+3.  **Factory Closure Pattern**: Inject runtime factory functions (`fnZeroSpaceFactory`, `fnDefaultLocalSpaceFactory`) into the `Metaspace_Nodespace` that capture the `domainRootPath` in their closure.
+4.  **Metaspace Orchestration**: Bootstrap the isolated domain and its private user space.
+5.  **Keystone Evolution**: Execute authorized evolutions within that isolated boundary.
+
+### Factory Closure Pattern
+To isolate domains without modifying core library types:
+-   **Runtime Injection**: The `MetaspaceFactory` is created dynamically per request (or domain).
+-   **Closure Capture**: The factory functions capture the calculated `domainRootPath` in their scope.
+-   **Zero Space Localization**: `fnZeroSpaceFactory` initializes the `NodeFilesystemSpace_V1` with the captured `baseDir`.
+-   **New Space Localization**: `fnDefaultLocalSpaceFactory` ensures any new local spaces created (e.g. on first run) are placed within the domain's subfolder.
+
+### Future Evolution
+*   **Sharding (V2+)**: The deterministic `tjpGib`-to-path mapping allows load balancers to route requests to specific shards without needing stateful knowledge of the user's location.
+*   **Manual Balancing (V3+)**: A future migration/balancing layer can add an optional stateful mapping to override default locations when domains need to move across physical nodes.
+
+---
+
+## Directory Structure
+
+```
+apps/space-gib/
+├── src/
+│   ├── client/                   ← Browser SPA (ibgib-create-app skill pattern)
+│   │   ├── index.html
+│   │   ├── index.mts
+│   │   ├── script.mts
+│   │   ├── bootstrap.mts
+│   │   ├── constants.mts
+│   │   ├── types.mts
+│   │   ├── helpers.web.mts
+│   │   ├── style.css
+│   │   ├── app/                  ← App Witness (ibgib-create-app-witness skill)
+│   │   │   ├── space-gib-app.mts
+│   │   │   ├── space-gib-app-constants.mts
+│   │   │   ├── space-gib-app-helpers.mts
+│   │   │   └── space-gib-app-types.mts
+│   │   ├── shell/                ← UI Shell (ibgib-create-shell skill)
+│   │   │   ├── space-gib-shell.mts
+│   │   │   ├── space-gib-shell-constants.mts
+│   │   │   └── space-gib-shell-types.mts
+│   │   └── components/           ← ibgib components (ibgib-create-component skill)
+│   │       └── space-main/
+│   │           ├── space-main.mts
+│   │           ├── space-main.html
+│   │           └── space-main.css
+│   └── server/                   ← Node.js API server
+│       ├── server.mts            ← Express entry point
+│       ├── space.mts             ← NodeFilesystemSpace_V1 singleton wrapper
+│       ├── middleware/
+│       │   └── validate-keystone.mts  ← Middleware: verify evolution proof before write
+│       └── routes/
+│           ├── ibgib.routes.mts       ← /api/ibgib/* routes
+│           └── keystone.routes.mts    ← /api/keystone/* routes
+├── dist/
+│   ├── client/                   ← Compiled SPA output
+│   └── server/                   ← Compiled Node.js output
+├── Dockerfile
+├── nginx.conf                    ← NOT used; kept for reference only
+├── package.json
+├── tsconfig.json                 ← Client compilation (browser target)
+└── tsconfig.server.json          ← Server compilation (Node.js target, ESM)
+```
+
+---
+
+## API Routes
+
+All routes are under `/api/`. SPA is served at all other paths.
+
+### IbGib Routes (`/api/ibgib/`)
+
+```
+POST   /api/ibgib
+  Body:   { ibGib: IbGib_V1 }           ← single ibgib
+  Or:     { ibGibs: IbGib_V1[] }        ← batch (pack)
+  Auth:   none (genesis/content ibgibs are self-legitimizing)
+  Notes:  server validates internal ibgib structure; stores via NodeFilesystemSpace_V1
+
+GET    /api/ibgib/:domainAddr/:ibGibAddr
+  Param:  domainAddr = URL-encoded domain keystone address
+  Param:  ibGibAddr = URL-encoded ib^gib address
+  Query:  ?getLatest=true|false (default false) — resolves the given addr to its latest timeline tip
+  Query:  ?getGraph=true|false (default false) — returns the entire dependency graph instead of a single ibgib
+  Query:  ?addrOnly=true|false (default false) — strips the response down to address(es) only, skipping ibgib body transmission.
+          - With getGraph=false: returns { addr, clientAddr } — cheap tip-check; if addr !== clientAddr, sync is needed.
+          - With getGraph=true: fetches the graph but returns { addr, clientAddr, addrs: string[] } — address manifest
+            for delta negotiation (client compares addrs against what it already has to compute the missing set).
+  Auth:   none (all reads are public)
+  Returns (single): { ibGib: IbGib_V1 } or 404
+  Returns (graph): { addr: string, count: number, graph: Record<string, IbGib_V1> } or 404
+  Returns (addrOnly, no graph): { addr: string, clientAddr: string }
+  Returns (addrOnly + graph): { addr: string, clientAddr: string, addrs: string[] }
+  Notes:  If getGraph is true, server walks rel8ns recursively. May be large.
+
+POST   /api/ibgib/pack
+  Body:   { knownAddrs: IbGibAddr[] }   ← addresses the client already has
+  Auth:   none
+  Returns: { ibGibs: IbGib_V1[] }       ← only the missing ones
+  Notes:  future expansion for incremental graph sync (requires HTTP/2 or WebSocket)
+```
+
+### Keystone Routes (`/api/keystone/`)
+
+```
+POST   /api/keystone
+  Body:   { ibGib: KeystoneIbGib_V1 }   ← genesis frame (first frame, no prior)
+  Auth:   none (genesis is self-legitimizing)
+  Returns: { addr: IbGibAddr, tjpGib: Gib }
+  Notes:  server validates internal keystone structure; stores genesis frame
+
+PUT    /api/keystone/evolve/:addr
+  Param:  addr = URL-encoded CURRENT TIP's full ib^gib address (CAS token)
+  Body:   { ibGib: KeystoneIbGib_V1 }   ← the new evolution frame (pre-computed by client)
+  Auth:   implicit — valid challenge solutions in the frame ARE the auth
+  Returns: { addr: IbGibAddr }           ← address of the accepted new frame
+  Error:  409 Conflict if :addr is not the current tip (stale — client must retry)
+  Notes:  server validates: (1) chain continuity (hash pre-images match commitments),
+          (2) CAS check (:addr === current tip). Rejects if either fails.
+
+GET    /api/keystone/:domainAddr
+  Param:  domainAddr = URL-encoded full ib^gib address (any frame OR tjpGib)
+  Query:  ?getLatest=true|false (default true) — resolves the keystone to its latest evolution
+  Query:  ?getGraph=true|false (default true) — returns the entire keystone timeline chain map
+  Auth:   none
+  Returns: { domainGraph: Record<string, KeystoneIbGib_V1> }  ← genesis to current tip mapped by address
+  Notes:  domainAddr is always the full keystone address, never just the tjpGib. The tjpGib is used as an id sometimes, but an api addr param must be the full address.
+```
+
+**On `/evolve` vs bare `PUT /api/keystone/:addr`:**
+We use `PUT /api/keystone/evolve/:addr` (not `PUT /api/keystone/:addr`) because:
+- Evolution has distinct server-side semantics: chain continuity check + CAS
+- Avoids router ambiguity with the `GET /api/keystone/:domainAddr` route
+- The `:domainAddr` being BEFORE the route specific term makes native Node routing more complicated
+- Explicit `/evolve` makes intent clear in logs, proxies, and future middleware
+
+---
+
+## Server Entry Point Sketch
+
+```typescript
+// src/server/server.mts
+import * as http from 'http';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { readFileSync, statSync } from 'fs';
+
+const PORT = process.env.PORT ?? 3000;
+const CLIENT_DIST = join(dirname(fileURLToPath(import.meta.url)), '../client');
+
+const server = http.createServer((req, res) => {
+    try {
+        const url = new URL(req.url || '/', `http://${req.headers.host}`);
+
+        // Basic CORS
+        res.setHeader('Access-Control-Allow-Origin', '*');
+        res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, OPTIONS');
+        res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+
+        if (req.method === 'OPTIONS') {
+            res.writeHead(204);
+            res.end();
+            return;
+        }
+
+        // API routes
+        if (url.pathname.startsWith('/api/ibgib/')) {
+            // ... handle ibgib routes natively
+            return;
+        }
+        if (url.pathname.startsWith('/api/keystone/')) {
+            // ... handle keystone routes natively
+            return;
+        }
+
+        // SPA fallback — serve static files
+        let filePath = join(CLIENT_DIST, url.pathname === '/' ? 'index.html' : url.pathname);
+        try {
+            if (!statSync(filePath).isFile()) filePath = join(CLIENT_DIST, 'index.html');
+        } catch {
+            filePath = join(CLIENT_DIST, 'index.html');
+        }
+
+        const content = readFileSync(filePath);
+        res.writeHead(200);
+        res.end(content);
+
+    } catch (err) {
+        res.writeHead(500);
+        res.end('Internal Server Error');
+    }
+});
+
+server.listen(PORT, () => console.log(`space-gib listening on :${PORT}`));
+```
+
+---
+
+## Space Singleton Sketch
+
+```typescript
+// src/server/space.mts
+import { NodeFilesystemSpace_V1 } from '@ibgib/core-gib/dist/witness/space/filesystem-space/node-filesystem-space/node-filesystem-space-v1.mjs';
+
+const DATA_DIR = process.env.DATA_DIR ?? '/data/ibgib-space';
+
+let _space: NodeFilesystemSpace_V1 | null = null;
+
+export async function getSpace(): Promise<NodeFilesystemSpace_V1> {
+    if (!_space) {
+        _space = new NodeFilesystemSpace_V1({ baseDir: DATA_DIR });
+        await _space.initialized;
+    }
+    return _space;
+}
+```
+
+---
+
+## IbGib Routes Sketch
+
+```typescript
+// src/server/routes/ibgib.routes.mts
+// ... implemented using native node http Request/Response parsing ...
+```
+
+---
+
+## Keystone Routes Sketch
+
+```typescript
+// src/server/routes/keystone.routes.mts
+// ... implemented using native node http Request/Response parsing ...
+```
+
+---
+
+## Dockerfile
+
+```dockerfile
+FROM node:22-alpine
+WORKDIR /app
+
+# Server runtime
+COPY dist/server ./server
+
+# Client SPA (served as static files)
+COPY dist/client ./client
+
+# Only production deps
+COPY package.json package-lock.json ./
+RUN npm ci --omit=dev
+
+ENV PORT=3000
+ENV DATA_DIR=/data/ibgib-space
+
+EXPOSE 3000
+CMD ["node", "server/server.mjs"]
+```
+
+---
+
+## docker-compose Additions
+
+**`docker-compose.yml`** (base / local):
+```yaml
+  space-gib:
+    build: ./apps/space-gib
+    volumes:
+      - ibgib_space_data:/data/ibgib-space
+    labels:
+      - "traefik.enable=true"
+      - "traefik.http.routers.space-gib.rule=Host(`space.ibgib.localhost`)"
+      - "traefik.http.routers.space-gib.entrypoints=websecure"
+      - "traefik.http.routers.space-gib.tls=true"
+      - "traefik.http.services.space-gib.loadbalancer.server.port=3000"
+
+volumes:
+  ibgib_space_data:
+```
+
+**`docker-compose.prod.yml`**:
+```yaml
+  space-gib:
+    labels:
+      - "traefik.http.routers.space-gib.rule=${SPACE_GIB_HOST_RULE:-Host(`ibgib.space`)}"
+      - "traefik.http.routers.space-gib.tls.certresolver=myresolver"
+    restart: always
+```
+
+---
+
+## package.json Shape
+
+```json
+{
+  "name": "@ibgib/space-gib",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "description": "ibgib storage and provider service — SaaS at ibgib.space",
+  "scripts": {
+    "build:client": "node ../../build/dist/concrete-build/build-space-gib.mjs",
+    "build:server": "tsc -p tsconfig.server.json",
+    "build": "npm run build:client && npm run build:server",
+    "start": "node dist/server/server.mjs",
+    "dev:server": "node --watch dist/server/server.mjs"
+  },
+  "dependencies": {
+    "@ibgib/core-gib": "*",
+    "@ibgib/web-gib": "*"
+  },
+  "devDependencies": {
+  },
+  "engines": { "node": ">=22.0.0" }
+}
+```
+
+---
+
+## tsconfig.server.json Shape
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "./dist/server",
+    "rootDir": "./src/server",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/server/**/*.mts"],
+  "exclude": ["node_modules", "dist"]
+}
+```
+
+---
+
+## Implementation Phases
+
+### Phase 1: Scaffold Client SPA
+- Use `ibgib-create-app` skill to generate the 4-panel SPA in `src/client/`
+- Tokens: `APP_NAME=space-gib`, `APP_CLASSNAME_PREFIX=SpaceGib`
+- Initial component: `space-main` — displays a placeholder four-panel layout
+- No real data yet; just confirms the SPA builds and the Docker image boots
+
+### Phase 2: Server Skeleton + Storage
+- Create `src/server/server.mts`, `space.mts`, route files
+- Wire up `NodeFilesystemSpace_V1` with Docker volume
+- Implement and manually test:
+  - `POST /api/ibgib` (store any ibgib)
+  - `GET /api/ibgib/:addr` (retrieve by full addr)
+  - `GET /api/ibgib/graph/:addr` (recursive graph walk)
+- Write `tsconfig.server.json` and `Dockerfile`
+- Add to `docker-compose.yml`
+
+### Phase 3: Keystone Operations
+- Implement `POST /api/keystone` (genesis)
+- Implement `PUT /api/keystone/evolve/:addr` with CAS + chain continuity check
+  - Uses `KeystoneService_V1.validate()` from `@ibgib/core-gib`
+  - Implement `getKeystoneTip()` via space metastone lookup
+- Implement `GET /api/keystone/:addr` (full chain retrieval)
+
+### Phase 4: Manifest + Scoped Writes
+- Server-side manifest ibgib creation (given a list of content addrs → create manifest ibgib)
+- Enforce: any content write must be accompanied by a valid keystone evolution
+  whose `claim.target` = the manifest's addr
+- Validate soft-link parent reference when creating child keystones
+- New route: `POST /api/manifest` → creates manifest ibgib from dependency list
+
+### Phase 5: Client Wires Up
+- `space-main` component navigates keystone hierarchy
+- Create keystone UI (calls `POST /api/keystone`)
+- Evolve keystone UI (client computes evolution, calls `PUT /api/keystone/evolve/:addr`)
+- Browse/view ibgib content in space
+
+### Phase 6: Comment Ibgib Use Case
+- Client creates comment ibgib using existing ibgib transform machinery
+- Server creates manifest from resulting dependency graph
+- Full end-to-end: create comment → manifest → evolve context keystone → store content
+
+---
+
+## Key Known Constraints
+
+- **Long path mitigation**: `NodeFilesystemSpace_V1` has `mitigateLongPaths=true` by default.
+  Ibgib addresses can exceed 255 chars; the space hashes long paths into a `long/` subdir.
+  This is a known pain point — be aware when debugging missing ibgibs.
+- **No auth on reads**: by design; all ibgibs are public. Write auth via keystone proofs only.
+- **CAS on keystone evolve**: clients must retry on 409. The retry loop is the client's
+  responsibility. No server-side locking.
+- **Single space instance**: the server is a singleton wrapper; one `NodeFilesystemSpace_V1`
+  per process. Horizontal scaling requires a shared storage backend (Postgres — future).

package/README.md

@@ -0,0 +1,46 @@
+# Space-Gib
+
+Space-Gib is the multitenant synchronization peer and hosting environment for the IbGib ecosystem. It features a Node.js Express/serve-gib backend and a dynamic SPA client frontend.
+
+## Local Development Workflow
+
+The local development environment uses a dual-target `esbuild` watch process and Docker for hosting the Node.js server behind a Traefik reverse proxy.
+
+To run the full development loop, open three separate terminal windows:
+
+### Terminal 1: Watch (Client & Server)
+Run the watch process to continuously type-check and bundle both client and server source files.
+```bash
+npm run watch:space-gib
+```
+
+### Terminal 2: Run (Docker)
+Start the Docker environment (Traefik + Node container).
+```bash
+npm run docker:space-gib
+```
+Once started, the application is available at **https://space-gib.localhost**
+
+### Terminal 3: Restart (As needed)
+Because the Node.js process runs inside Docker, hot-reloading the server code requires restarting the container.
+* Client changes: Auto-reload when you refresh the browser.
+* Server changes: Run this command to load your newly compiled server code.
+```bash
+npm run restart:space-gib
+```
+
+## Directory Structure
+
+* [`src/client/`](src/client/): The browser SPA frontend. [See Client README](src/client/README.md).
+* [`src/server/`](src/server/): The Node.js server. [See Server README](src/server/README.md).
+* [`src/common/`](src/common/): Shared logic, types, and constants used by both client and server.
+  > [!IMPORTANT]
+  > **STRICT RULE**: `src/common` MUST NEVER import from `src/client` or `src/server`. This ensures the shared layer remains portable and prevents circular dependencies.
+* [`dist/`](dist/): The output directory where `esbuild` writes the bundled client (`dist/client/`) and server (`dist/server/`) code.
+
+## Debugging the Server
+
+You can attach the VS Code debugger directly to the Node.js process running inside Docker.
+1. The server runs with the `--inspect=0.0.0.0:9229` flag.
+2. `docker-compose.yml` maps port `9229` to your host machine.
+3. Use the VS Code launch configuration `Docker: Attach to Space-Gib` to attach breakpoints.