@tangle-network/starter-foundry 0.5.4 → 0.7.0

package/registry/layers/framework/legal-case-mgmt/files/server.ts

@@ -0,0 +1,50 @@
+import http from 'node:http'
+import { getMatter, listUnbilledTime, logTimeEntry, openMatter } from './api/matter.ts'
+import { draftInvoiceRoute } from './api/billing.ts'
+
+const port = Number.parseInt(process.env.PORT ?? '{{port}}', 10)
+
+const server = http.createServer(async (request, response) => {
+  const url = new URL(request.url ?? '/', `http://127.0.0.1:${port}`)
+
+  if (url.pathname === '/health') {
+    response.writeHead(200, { 'content-type': 'application/json' })
+    response.end(JSON.stringify({ status: 'ok', service: '{{serviceName}}' }))
+    return
+  }
+
+  if (url.pathname === '/api/matters' && request.method === 'POST') {
+    await openMatter(request, response)
+    return
+  }
+
+  const matterMatch = /^\/api\/matters\/([^/]+)$/.exec(url.pathname)
+  if (matterMatch && request.method === 'GET') {
+    await getMatter(request, response, matterMatch[1] ?? '')
+    return
+  }
+
+  const timeMatch = /^\/api\/matters\/([^/]+)\/time-entries$/.exec(url.pathname)
+  if (timeMatch && request.method === 'POST') {
+    await logTimeEntry(request, response, timeMatch[1] ?? '')
+    return
+  }
+  if (timeMatch && request.method === 'GET') {
+    await listUnbilledTime(request, response, timeMatch[1] ?? '')
+    return
+  }
+
+  const invoiceMatch = /^\/api\/matters\/([^/]+)\/invoice\/draft$/.exec(url.pathname)
+  if (invoiceMatch && request.method === 'POST') {
+    await draftInvoiceRoute(request, response, invoiceMatch[1] ?? '')
+    return
+  }
+
+  response.writeHead(404, { 'content-type': 'application/json' })
+  response.end(JSON.stringify({ error: 'not found' }))
+})
+
+server.listen(port, '0.0.0.0', () => {
+  // eslint-disable-next-line no-console
+  console.log(`{{serviceName}} listening on ${port}`)
+})

package/registry/layers/framework/legal-case-mgmt/files/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "noEmit": true,
+    "allowImportingTsExtensions": true
+  },
+  "include": ["src/**/*.ts", "drizzle.config.ts"]
+}

package/registry/layers/framework/legal-case-mgmt/files/validate-legal.mjs

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import { readFileSync, existsSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const pkg = JSON.parse(readFileSync(join(here, 'package.json'), 'utf8'))
+
+if (!pkg.dependencies?.['drizzle-orm']) throw new Error('drizzle-orm missing from dependencies')
+if (!pkg.dependencies?.['decimal.js']) throw new Error('decimal.js missing from dependencies')
+if (!pkg.dependencies?.['postgres']) throw new Error('postgres missing from dependencies')
+
+const required = [
+  'tsconfig.json',
+  'src/server.ts',
+  'src/db/schema.ts',
+  'src/db/client.ts',
+  'src/api/matter.ts',
+  'src/api/billing.ts',
+  'drizzle.config.ts',
+]
+for (const rel of required) {
+  if (!existsSync(join(here, rel))) throw new Error(`missing required file: ${rel}`)
+}
+
+console.log('legal starter ok')

package/registry/layers/framework/legal-case-mgmt/manifest.json

@@ -0,0 +1,79 @@
+{
+  "id": "legal-case-mgmt",
+  "description": "Legal practice management framework layer — Drizzle ORM schema for matters/parties/documents/time-entries/billing-rates/invoices, Node http REST routes, and decimal-safe invoice draft generation.",
+  "appliesTo": ["legal-case-mgmt"],
+  "files": [
+    { "source": "files/package.json", "target": "package.json" },
+    { "source": "files/tsconfig.json", "target": "tsconfig.json" },
+    { "source": "files/server.ts", "target": "src/server.ts" },
+    { "source": "files/schema.ts", "target": "src/db/schema.ts" },
+    { "source": "files/db.ts", "target": "src/db/client.ts" },
+    { "source": "files/matter.ts", "target": "src/api/matter.ts" },
+    { "source": "files/billing.ts", "target": "src/api/billing.ts" },
+    { "source": "files/drizzle.config.ts", "target": "drizzle.config.ts" },
+    { "source": "files/.env.example", "target": ".env.example" },
+    { "source": "files/AGENTS.md", "target": "AGENTS.md" },
+    { "source": "files/validate-legal.mjs", "target": "validate-legal.mjs" }
+  ],
+  "packageDeps": {
+    "dependencies": {
+      "drizzle-orm": "^0.36.0",
+      "postgres": "^3.4.5",
+      "decimal.js": "^10.4.3"
+    },
+    "devDependencies": {
+      "drizzle-kit": "^0.30.0",
+      "typescript": "^5.9.0",
+      "@types/node": "^20.17.0"
+    }
+  },
+  "buildHints": {
+    "whenToUse": "Building a law-firm SaaS API that needs matter tracking, attorney time-keeping, content-addressed document retention, and billing. Supplies the full Drizzle schema, six REST endpoints, and decimal-safe invoice generation out of the box.",
+    "firstSteps": [
+      "Copy .env.example to .env and set DATABASE_URL to a Postgres 15+ connection string.",
+      "Run `pnpm install` then `pnpm db:generate && pnpm db:migrate` to create all tables.",
+      "Run `pnpm dev` — server starts on port 8102; verify with `curl http://localhost:8102/health`.",
+      "Seed a client row directly in the DB (or add POST /api/clients), then POST /api/matters with { clientId, matterNumber, title }.",
+      "Insert at least one billing_rates row for the attorney before drafting an invoice.",
+      "POST /api/matters/:id/time-entries with { attorneyId, workedAt (ISO), minutes (integer), narrative } to log time.",
+      "POST /api/matters/:id/invoice/draft aggregates all unbilled billable entries into a draft Invoice row.",
+      "Routes: GET /health · POST /api/matters · GET /api/matters/:id · POST /api/matters/:id/time-entries · GET /api/matters/:id/time-entries · POST /api/matters/:id/invoice/draft"
+    ],
+    "gotchas": [
+      "Time entries MUST be stored in minutes (positive integer), not fractional hours. Rounding 0.1h + 0.1h across 200 entries drifts real dollars.",
+      "Hourly rates MUST use integer cents — billing.ts uses decimal.js for all arithmetic. Never convert to float before arithmetic.",
+      "Documents are IMMUTABLE under retention obligations. Do NOT add UPDATE or DELETE endpoints for the documents table — amendments are new rows referencing the prior contentHash.",
+      "Attorney-client privilege: access control MUST be enforced at the matter level, not just the document level. Leaking matter title or party names to the wrong client is still a privilege breach.",
+      "Trust / IOLTA accounting is SEPARATE from the operating ledger — commingling is a bar-disciplinary offense. If this service handles trust funds it needs its own chart of accounts with explicit segregation.",
+      "Conflicts checking is NOT implemented — before opening a matter in production, check all party names against every prior matter including opposing parties.",
+      "Billable-hours rounding convention varies by firm (6-minute increments is common). Store raw minutes; apply firm rounding at invoice generation time inside billing.ts.",
+      "Retention: many jurisdictions require 5–7 years after matter closure. Soft-delete + lifecycle policy; never hard-delete document rows."
+    ],
+    "architectureNotes": [
+      "Matter-centric schema: every party, document, time entry, and invoice belongs to a Matter. This mirrors the legal concept of 'matter' as the unit of work and the unit of privilege.",
+      "Documents are content-addressed: content_hash = sha256(bytes) is the primary identity. Replacing a document creates a new row; the old row is never mutated.",
+      "Time entries are immutable once invoiced — draftInvoice() sets invoice_id FK inside a transaction; callers cannot unset it.",
+      "Billing rates are time-bounded (effectiveAt). billing.ts resolves each entry to the rate effective at entry.workedAt so historical invoices stay accurate after a rate change.",
+      "Invoice draft runs in one DB transaction: aggregate unbilled entries → compute amounts via Decimal → insert Invoice → set invoice_id on each entry. Avoids double-billing on retry.",
+      "Data models: clients · attorneys · matters · parties · documents · billing_rates · invoices · time_entries. See src/db/schema.ts for full Drizzle column/index definitions."
+    ],
+    "placeholders": [
+      {
+        "path": "src/server.ts",
+        "description": "{{port}} is replaced with the numeric port from family defaults (8102). {{serviceName}} is replaced with the service name. After compose these are literal strings."
+      }
+    ]
+  },
+  "contextHints": {
+    "commands": [
+      "pnpm install",
+      "pnpm dev",
+      "pnpm db:generate",
+      "pnpm db:migrate",
+      "pnpm validate"
+    ],
+    "entrypoints": ["src/server.ts", "src/db/schema.ts", "src/api/matter.ts", "src/api/billing.ts"],
+    "preview": { "path": "/health" },
+    "extensionPoints": ["src/db/schema.ts", "src/api/"]
+  }
+}

package/registry/layers/framework/livekit-sfu/files/AGENTS.md

@@ -0,0 +1,76 @@
+# AGENTS.md — {{serviceName}} (LiveKit SFU)
+
+This is a **self-hosted WebRTC SFU** starter. The LiveKit server runs in Docker; a
+Node/Express control plane (`src/server.ts`) mints short-lived JWT access tokens so
+browser clients can join rooms.
+
+## Prerequisites
+
+- Docker (or Docker Desktop)
+- pnpm ≥ 9
+
+## Commands
+
+```bash
+# Install dependencies
+pnpm install
+
+# Start the SFU + Redis sidecar (detached)
+docker compose up -d
+
+# Start the token-minting control plane (hot-reload)
+pnpm dev
+
+# Mint a token for a client
+curl -X POST http://localhost:{{controlPort}}/token \
+  -H 'Content-Type: application/json' \
+  -d '{"room":"demo","identity":"alice"}'
+
+# Check control-plane health
+curl http://localhost:{{controlPort}}/health
+
+# Typecheck without emitting files
+pnpm exec tsc --noEmit
+
+# Tear down Docker services
+docker compose down
+```
+
+## Project structure
+
+| Path | Purpose |
+|------|---------|
+| `src/server.ts` | Express token server — **only file you need to edit** for most features |
+| `docker-compose.yml` | LiveKit SFU + Redis sidecar; uses `network_mode: host` for ICE |
+| `livekit.yaml` | SFU config: ports, external-IP discovery, API key/secret, Redis address |
+| `.env.example` | Copy to `.env` and fill in real credentials before deploying |
+| `validate-livekit.mjs` | Structural smoke-test — run with `node validate-livekit.mjs` |
+
+## First steps
+
+1. Copy `.env.example` → `.env`. The dev defaults work locally; replace secrets for production.
+2. `docker compose up -d` to start the SFU.
+3. `pnpm dev` to start the control plane on port `{{controlPort}}`.
+4. Mint a token and pass `token` + `wsUrl` to the browser's `livekit-client`:
+   ```ts
+   import { Room } from 'livekit-client'
+   const room = new Room()
+   await room.connect(wsUrl, token)
+   ```
+
+## Extending `src/server.ts`
+
+- **Role-based access** — set `canPublish: false` in the `VideoGrant` for viewer-only identities.
+- **Custom TTL** — pass `ttlSeconds` in the POST body (clamped to 60–86400 s).
+- **Extra routes** — add REST endpoints above `app.listen`; keep token-signing logic in one place.
+- **Auth middleware** — add `app.use(verifyJwt)` before the `/token` route to gate who can mint tokens.
+
+## Critical rules
+
+- `LIVEKIT_API_SECRET` must be **≥ 32 bytes**. The server throws at startup if shorter.
+  Generate a safe value: `openssl rand -base64 32`
+- The same key/secret pair must appear in **both** `.env` (control plane) **and** `livekit.yaml`
+  under `keys:` (SFU). A mismatch causes 401s when clients try to join rooms.
+- `getUserMedia` requires **HTTPS** outside `localhost` — clients cannot publish tracks over plain HTTP.
+- The SFU uses `network_mode: host`; standard `ports:` mapping will not work for ICE/UDP traffic.
+- Access tokens expire (default TTL 6 h). Clients must re-request before expiry or the WS upgrade is rejected.

package/registry/layers/framework/livekit-sfu/files/server.ts

@@ -0,0 +1,84 @@
+// LiveKit SFU control plane.
+//
+// The SFU itself runs in docker (`docker compose up -d`). This Express server
+// is the thin trusted boundary that mints access tokens: browser clients call
+// POST /token with a desired room + identity, we sign a JWT using the same
+// key/secret the SFU is configured with, and the client uses that JWT to
+// open a WebSocket into the SFU.
+//
+// Keep all signing server-side. Never ship the API secret to the browser.
+
+import express from 'express'
+import { AccessToken, type VideoGrant } from 'livekit-server-sdk'
+
+const controlPort = Number(process.env.CONTROL_PORT ?? '{{controlPort}}')
+const apiKey = process.env.LIVEKIT_API_KEY ?? '{{livekitApiKey}}'
+const apiSecret = process.env.LIVEKIT_API_SECRET ?? '{{livekitApiSecret}}'
+const wsUrl = process.env.LIVEKIT_WS_URL ?? 'ws://localhost:{{port}}'
+
+// HMAC key must be ≥32 bytes or the LiveKit server refuses to accept tokens
+// signed by it. Fail-closed at boot rather than mint unusable JWTs.
+if (apiSecret.length < 32) {
+  throw new Error(
+    `LIVEKIT_API_SECRET must be ≥32 bytes (got ${apiSecret.length}). ` +
+      `Generate one with: openssl rand -base64 32`,
+  )
+}
+
+interface TokenRequest {
+  room: string
+  identity: string
+  // Optional grants — default is publish+subscribe on the named room.
+  canPublish?: boolean
+  canSubscribe?: boolean
+  canPublishData?: boolean
+  ttlSeconds?: number
+}
+
+const app = express()
+app.use(express.json({ limit: '16kb' }))
+
+app.get('/health', (_req, res) => {
+  res.json({
+    status: 'ok',
+    service: '{{serviceName}}',
+    wsUrl,
+    apiKey,
+  })
+})
+
+app.post('/token', (req, res) => {
+  const body = req.body as Partial<TokenRequest>
+  if (!body.room || typeof body.room !== 'string') {
+    return res.status(400).json({ error: 'room is required (string)' })
+  }
+  if (!body.identity || typeof body.identity !== 'string') {
+    return res.status(400).json({ error: 'identity is required (string)' })
+  }
+
+  const ttl = Math.min(Math.max(body.ttlSeconds ?? 6 * 60 * 60, 60), 24 * 60 * 60)
+
+  const at = new AccessToken(apiKey, apiSecret, {
+    identity: body.identity,
+    ttl,
+  })
+
+  const grant: VideoGrant = {
+    room: body.room,
+    roomJoin: true,
+    canPublish: body.canPublish ?? true,
+    canSubscribe: body.canSubscribe ?? true,
+    canPublishData: body.canPublishData ?? true,
+  }
+  at.addGrant(grant)
+
+  return at.toJwt().then((jwt) => {
+    res.json({ token: jwt, wsUrl, room: body.room, identity: body.identity, ttl })
+  })
+})
+
+app.listen(controlPort, () => {
+  console.log(`{{serviceName}} control plane on http://localhost:${controlPort}`)
+  console.log(`  SFU WebSocket:   ${wsUrl}`)
+  console.log(`  Mint token:      POST /token  { room, identity }`)
+})

package/registry/layers/framework/livekit-sfu/manifest.json

@@ -0,0 +1,67 @@
+{
+  "id": "livekit-sfu",
+  "description": "LiveKit SFU control plane — Express server that mints short-lived JWT access tokens so browser clients can join rooms with scoped grants.",
+  "appliesTo": ["livekit-sfu"],
+  "files": [
+    {
+      "source": "files/server.ts",
+      "target": "src/server.ts"
+    },
+    {
+      "source": "files/AGENTS.md",
+      "target": "AGENTS.md"
+    }
+  ],
+  "packageDeps": {
+    "dependencies": {
+      "express": "^4.21.2",
+      "livekit-server-sdk": "^2.9.2"
+    },
+    "devDependencies": {
+      "@types/express": "^4.17.21",
+      "@types/node": "^20.17.0",
+      "tsx": "^4.19.2",
+      "typescript": "^5.9.0"
+    }
+  },
+  "buildHints": {
+    "whenToUse": "Self-hosted WebRTC rooms — audio/video conferencing, group voice chat, live streaming, Clubhouse/Twitter-Spaces-style audio rooms, or any product that needs server-side JWT room grants without relying on a third-party SFU cloud.",
+    "firstSteps": [
+      "Copy `.env.example` to `.env` and set `LIVEKIT_API_KEY` / `LIVEKIT_API_SECRET` (secret ≥32 bytes); mirror the same pair in `livekit.yaml` under `keys:`.",
+      "Run `docker compose up -d` to start the LiveKit SFU + Redis sidecar, then `pnpm dev` to start the token-minting control plane on port 8098.",
+      "Mint a token: `curl -X POST http://localhost:8098/token -H 'Content-Type: application/json' -d '{\"room\":\"demo\",\"identity\":\"alice\"}'` — response includes `token` and `wsUrl` ready for a LiveKit client SDK.",
+      "In the browser, pass those values to `new Room().connect(wsUrl, token)` from `livekit-client`.",
+      "Verify the control plane is live: `curl http://localhost:8098/health`."
+    ],
+    "gotchas": [
+      "LIVEKIT_API_SECRET must be ≥32 bytes — the server throws at startup if shorter. Generate one with: `openssl rand -base64 32`.",
+      "The same API key/secret pair must appear in BOTH `.env` (for the control plane) AND `livekit.yaml` under `keys:` (for the SFU). A mismatch causes 401s when clients try to join rooms.",
+      "getUserMedia requires HTTPS outside localhost — browser clients cannot publish tracks over plain HTTP.",
+      "The LiveKit SFU uses `network_mode: host` in docker-compose so WebRTC clients can reach the real port range (UDP 50000-60000). Port mapping (`ports:`) won't work for ICE traffic.",
+      "Access tokens expire (default TTL 6h). Browser clients must re-request a token before expiry or the SFU rejects the WS upgrade."
+    ],
+    "architectureNotes": [
+      "The Express server is the trusted boundary — it holds the API secret and mints JWTs; browser clients never see the secret.",
+      "Keep all signing server-side: `/token` accepts room + identity, returns a signed JWT; the browser uses the JWT directly with the LiveKit client SDK (`livekit-client`).",
+      "Redis is included for multi-node scale-out. A single-node deployment works without it, but keeping Redis in compose means horizontal scaling is a `docker compose up --scale livekit=N` away."
+    ],
+    "placeholders": [
+      {
+        "path": "src/server.ts",
+        "description": "Token-minting Express server. The `{{...}}` strings (livekitApiKey, livekitApiSecret, controlPort, port, serviceName) are substituted by the compose engine from family defaults. Extend the VideoGrant fields in the `/token` handler to implement role-based room access (e.g. read-only viewers set canPublish=false)."
+      }
+    ]
+  },
+  "contextHints": {
+    "commands": [
+      "pnpm install",
+      "docker compose up -d",
+      "pnpm dev",
+      "curl -X POST http://localhost:8098/token -H 'Content-Type: application/json' -d '{\"room\":\"demo\",\"identity\":\"alice\"}'",
+      "curl http://localhost:8098/health"
+    ],
+    "entrypoints": ["src/server.ts"],
+    "preview": { "path": "/health" },
+    "extensionPoints": ["src/server.ts", "livekit.yaml", ".env"]
+  }
+}

package/registry/layers/framework/lora-training/files/infer.py

@@ -0,0 +1,102 @@
+"""Load base + LoRA adapter and generate.
+
+    python infer.py --adapter ./outputs/lora-adapter --prompt "hello"
+
+Loads the base in 4-bit (matching training) and attaches the trained
+adapter on top. For production serving, use vLLM's --enable-lora with
+--lora-modules <name>=<path> for multi-adapter hot-swapping.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+import torch
+import yaml
+from dotenv import load_dotenv
+from peft import PeftModel
+from transformers import AutoModelForCausalLM, AutoTokenizer, BitsAndBytesConfig
+
+load_dotenv()
+
+
+def _load_base_id(adapter_dir: Path) -> str:
+    """Read the base model id PEFT records inside the adapter folder."""
+    cfg_path = adapter_dir / "adapter_config.json"
+    if cfg_path.exists():
+        with open(cfg_path, "r", encoding="utf-8") as f:
+            return json.load(f)["base_model_name_or_path"]
+    # Fallback: read the original train.yaml if the caller points at it.
+    train_yaml = Path("config/train.yaml")
+    if train_yaml.exists():
+        with open(train_yaml, "r", encoding="utf-8") as f:
+            return yaml.safe_load(f)["model"]["base_model_id"]
+    raise RuntimeError(
+        f"Could not determine base model id. Adapter at {adapter_dir} missing "
+        "adapter_config.json, and config/train.yaml not found."
+    )
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--adapter", type=Path, required=True, help="Path to saved LoRA adapter dir")
+    parser.add_argument("--prompt", type=str, required=True, help="Text prompt")
+    parser.add_argument("--max-new-tokens", type=int, default=256)
+    parser.add_argument("--temperature", type=float, default=0.7)
+    parser.add_argument("--no-4bit", action="store_true", help="Load base in bf16 instead of 4-bit")
+    args = parser.parse_args()
+
+    base_id = _load_base_id(args.adapter)
+    print(f"loading base {base_id} + adapter {args.adapter}")
+
+    tokenizer = AutoTokenizer.from_pretrained(base_id, trust_remote_code=True)
+    if tokenizer.pad_token is None:
+        tokenizer.pad_token = tokenizer.eos_token
+
+    bnb = None
+    if not args.no_4bit:
+        bnb = BitsAndBytesConfig(
+            load_in_4bit=True,
+            bnb_4bit_quant_type="nf4",
+            bnb_4bit_compute_dtype=torch.bfloat16,
+            bnb_4bit_use_double_quant=True,
+        )
+
+    base = AutoModelForCausalLM.from_pretrained(
+        base_id,
+        quantization_config=bnb,
+        torch_dtype=torch.bfloat16,
+        device_map="auto",
+        trust_remote_code=True,
+    )
+    model = PeftModel.from_pretrained(base, str(args.adapter))
+    model.eval()
+
+    # Use the same chat template the training data was formatted with.
+    messages = [{"role": "user", "content": args.prompt}]
+    input_text = tokenizer.apply_chat_template(
+        messages,
+        tokenize=False,
+        add_generation_prompt=True,
+    )
+    inputs = tokenizer(input_text, return_tensors="pt").to(model.device)
+
+    with torch.no_grad():
+        output = model.generate(
+            **inputs,
+            max_new_tokens=args.max_new_tokens,
+            temperature=args.temperature,
+            do_sample=args.temperature > 0,
+            top_p=0.95,
+            pad_token_id=tokenizer.pad_token_id,
+        )
+
+    generated = tokenizer.decode(output[0][inputs["input_ids"].shape[1] :], skip_special_tokens=True)
+    print(generated)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/registry/layers/framework/lora-training/files/pyrightconfig.json

@@ -0,0 +1,8 @@
+{
+  "typeCheckingMode": "basic",
+  "reportMissingImports": false,
+  "reportMissingModuleSource": false,
+  "reportUnknownVariableType": false,
+  "reportUnknownMemberType": false,
+  "reportUnknownArgumentType": false
+}