teamshare-bridge 0.1.0 → 0.2.0

package/skills/teamshare-cdd/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: teamshare-cdd
+description: Documents-driven development for TeamShare. Before any code, find and read the project's documents in the Documents tab (virtual folders: docs/, agents/<you>/tasks/<taskId>/). Write plan.md BEFORE starting, keep progress.md/notes updated while working (update_document_note), and close with summary.md. Uploads and markdown notes live in Cloudinary-backed virtual folders, never loose files.
+---
+
+# TeamShare Documents-Driven Development (CDD)
+
+You are working a task in a TeamShare project. In TeamShare, **the project's
+Documents tab is the source of truth** — the same way `docs/` + `AGENTS.md`
+drive TeamShare's own development at the repo root. Documents are organized
+in **virtual folders** (a lowercase path stored on each document; the UI
+renders them as a tree). Your job is to work from the docs, write the docs,
+and leave the task better documented than you found it.
+
+## The document library convention
+
+Every project document carries a `folderPath` (lowercase kebab segments, `/`
+= root, max 8 levels). The folders an agent creates MUST follow this layout:
+
+```
+docs/                              <- shared, project-wide knowledge
+├── contracts/                     <- API/endpoint contract notes
+├── adr/                           <- ADR-<n>-<title>.md architecture decisions
+└── guides/                        <- how-to guides for humans + agents
+agents/
+└── <agent-slug>/                  <- ONE folder per agent (short, stable slug)
+    └── tasks/
+        └── <taskId>/              <- per-task workspace
+            ├── plan.md            <- written BEFORE starting the work
+            ├── progress.md        <- updated while working (or rely on subtasks)
+            └── summary.md         <- written on completion
+reports/                           <- milestone reports (optional)
+```
+
+Rules that are not optional:
+
+- **Kebab-case** document names ending in `.md` (`.markdown`/`.txt` ok).
+- **Lowercase** folder paths; no spaces, no leading/trailing slashes.
+- **One folder per agent, one subfolder per task.** Never write outside your
+  own folder except into `docs/**` when you add shared knowledge.
+- Document names are unique enough to be obvious (`plan.md`, `progress.md`,
+  `summary.md`, `adr-001-auth-rbac.md`).
+
+## The workflow — three gates
+
+### START (before touching any code)
+1. `list_document_folders` + `list_documents` for the project.
+2. Read `docs/contracts`, `docs/adr`, `docs/guides` that exist — they govern
+   your implementation (same way `docs/api-contract.md` and
+   `docs/ui-style-guide.md` govern TeamShare's repos).
+3. Read your own task folder if this is a `--continue`/resumed session.
+4. **Write `plan.md` FIRST** via `create_document`: goal, decisions, files to
+   touch, step list. No code until the plan note exists.
+5. **Move the task to `in_progress`** via `update_task` — you are now working it.
+
+### DO (while working)
+6. Check off subtasks (`update_subtask done: true`) and update
+   `progress.md`/`plan.md` via `update_document_note` as you go — the human
+   watches the app.
+7. When you make an architecture decision worth keeping, add it to `docs/adr`
+   as `ADR-<n>-<title>.md` (short: context → decision → consequences).
+8. Blocked? Use `ask_human` and include a pointer to the relevant note.
+
+### DONE (before closing)
+9. **Move the task to `in_review`** via `update_task` — signals the human
+   to review your work.
+10. Write `summary.md`: what you built, why, how it maps to the plan, links to
+    related docs, follow-ups.
+11. Post the closing comment referencing the summary doc.
+12. Never leave a task without `plan.md` + `summary.md` notes.
+
+## Task status progression (guidance)
+
+Status can be set to **any value from any state** — the system allows free
+transitions and reversal. No blocking errors. Use this as a guideline:
+
+```
+open → in_progress → in_review → resolved → closed
+```
+
+| When | Set status to | Why |
+|---|---|---|
+| You start working the task | `in_progress` | You claimed it, work has begun |
+| Work is done, ready for human review | `in_review` | Human should review before you close |
+| Human approves your work | `resolved` | Approved, ready to close |
+| Final close (usually human) | `closed` | Task is fully complete |
+
+**Tip:** Set status as you go. The human sees live progress in the app.
+You can always reverse (e.g. `in_progress` → `open` if you need to reassess).
+Don't jump to `resolved` or `closed` unless the human explicitly approves —
+those are typically human-gated gates.
+
+## Build mode (IMP-700) — the project's workflow engine
+
+Some projects run **build mode**: the project has a build agent, and tasks
+marked **ready for dev** (`readyForDev: true`) form an ordered build queue
+(`sortOrder` asc, `createdAt` asc) that the agent works **strictly one at a
+time, fully completing each**. When you are working a task as part of a build
+run, the following rules apply ON TOP of everything above:
+
+- **Ready for dev is the gate.** A task stays out of the build queue until a
+  human (or the planner) sets `readyForDev: true`. The queue only contains
+  `readyForDev=true AND status=open` tasks (plus blocked in-progress ones).
+- **Strict order, full completion.** Work the queue in exact order — never
+  pick a later task while an earlier one is open. Do not move on until the
+  current task is genuinely complete: build passes, `plan.md` written first,
+  subtasks checked off, `summary.md` written, status moved to `in_review` or
+  `resolved`.
+- **Failure protocol (never block the queue).** If a task cannot be finished,
+  the BUILD LOOP (not you) handles it: it leaves a `[question]` comment on the
+  task (marked with the literal prefix `[question]`) and a message in the
+  project's `#agent-questions` channel, then continues with the next ready
+  task. When a human answers, the loop resumes the skipped task automatically.
+- **Planning (`--draft`).** When the human asks you to plan a build run from a
+  goal, create the tasks yourself with `create_task`:
+  - `readyForDev: true` so they enter the queue,
+  - increasing `sortOrder` (1, 2, 3, ...) so they are worked strictly in order,
+  - `assigneeId "me"` so the build agent owns them,
+  - dependencies first (a task that unblocks others comes before them),
+  - write the plan into `agents/<your-slug>/tasks/<taskId>/plan.md` per task,
+    and a shared `docs/guides/build-plan.md` note summarizing the order.
+- **Progress signals.** Push the task to `in_progress` when you start it and
+  `in_review` when done — the build loop watches status to decide
+  done vs. failed, so a task left in `in_progress` at the end of a session is
+  treated as failed and skipped.
+
+## Tools to use
+
+- `list_document_folders <projectId>` — the tree, with per-folder counts.
+- `list_documents <projectId>` — files (optionally filter by folder).
+- `read_document <documentId>` — content (notes return their markdown body).
+- `create_document` — write a note (`name`, `content`, `folderPath`).
+- `update_document_note <documentId> <content>` — replace a note's body.
+- Uploads (PDFs, images, binaries) are Cloudinary-hosted into
+  `documents/<folderPath>` and recorded as file documents — mirror the same
+  folder convention.
+
+## References
+
+- `docs/agent-tasks/agent-hub-connection.md` — the agent contract.
+- `docs/api-contract.md` — response envelope, pagination, type mirroring.
+- TeamShare root `docs/` + `IMPLEMENTATION_TRACKER.md` — the convention this
+  skill mirrors.
+- Backend: `GET /documents/folders`, `POST /documents/note`,
+  `PATCH /documents/:id/content`, `GET /documents/:id/raw`.

package/skills/teamshare-modularity/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: teamshare-modularity
+description: Enforce TeamShare's modular architecture when writing code in teamshare-backend, frontend, teamshare-mobile-app or teamshare-bridge. Follow the per-repo layout (src/modules/<feature>/{controller,service,dto,module}, src/components/{ui,shared}, modules/<feature>/{views,components,columns,hooks,utils}, src/lib/api per feature), never import vendor ui/ in app code, use TS* wrappers, zod-first DTOs, the response envelope, and pass the repo build/typecheck gates before done.
+---
+
+# TeamShare Modular Architecture Enforcement
+
+TeamShare is four separate repos with strict internal layouts. Before writing
+code, check which repo you are in and follow its module structure exactly.
+These rules are enforced per repo — know where you are.
+
+## 1. teamshare-backend (NestJS + Prisma 6 + zod)
+
+- **Layout:** a feature lives in `src/modules/<plural-feature>/` with
+  `<feature>.controller.ts`, `<feature>.service.ts`, `<feature>.dto.ts`,
+  `<feature>.module.ts` (+ `*.spec.ts`). Cross-cutting infra goes in
+  `src/common/<area>/` (constants, decorators, dto, filters, guards,
+  interceptors, pipes, prisma, utils, ...) — never inside a feature module.
+- **DTOs are zod-first:** `export const CreateXSchema = z.object({...})` +
+  `export type CreateXDto = z.infer<typeof ...>`. Validate via
+  `@Body(new ZodValidationPipe(Schema))`. Import enum schemas from
+  `src/generated/zod/schemas/enums/...`; never hand-edit `src/generated/zod`.
+- **Every endpoint returns the envelope** `{ success, data, pagination? }`
+  (TransformInterceptor) — handlers return raw data, lists return
+  `{ items, pagination }` via `computePagination`.
+- **Every endpoint declares access metadata** (`@Permissions`, or
+  `@Public()` + `@UseGuards(AgentsDualAuthGuard)` + `@ApiKeyScopes` for the
+  agent+human surface) — see the teamshare-auth-rbac skill.
+- **Prisma:** `prisma/schema.prisma` is the single source of truth. After a
+  schema change run `npx prisma generate` (do not hand-edit generated zod).
+  Deploy migrations with `npx prisma migrate deploy`, never `migrate dev`.
+- **Error style:** throw exceptions with a machine-readable `code`
+  (`new BadRequestException({ code: 'X', message: '...' })`).
+
+## 2. frontend (Next.js App Router + Tailwind v4 + TanStack Query)
+
+- **Two component layers, never mixed:**
+  - `src/components/ui/` = VENDOR shadcn primitives — do not edit, do not
+    import from app code.
+  - `src/components/shared/` = TeamShare `TS*` wrappers. **App code imports
+    ONLY from `@/components/shared`** (barrel `index.ts`). Build new shared
+    components here, named `TS*`, with `data-slot="ts-*"` and `--ts-*` tokens.
+- **Feature modules:** `src/modules/<feature>/{views,components,columns,hooks,utils}`.
+  Pages under `src/app/` stay thin and delegate to views. Route tabs use
+  `useUrlTab` (`?tab=...`).
+- **API + data:** per-feature `src/lib/api/<feature>.ts` exporting a
+  `<feature>Api` object of `listX/getX/createX/updateX/deleteX`; envelope-aware
+  `apiFetch` from `@/lib/api/client`. Query keys via `qk.*` factory
+  (`src/lib/query-keys.ts`), list state via `useListState`.
+- **Validation mirror:** zod schemas live in `src/lib/validation/schemas.ts`
+  and MIRROR the backend contract (backend is canonical). Enums derive from
+  the schemas in `src/lib/constants/enums.ts`.
+- **Tables/forms:** TanStack React Table **v8** inside `TSTable`; forms always
+  `TSForm` + `TSFormField` + `zodResolver`.
+- **IconSax hard rule:** `iconsax-react`, every icon passes `variant` AND
+  `color`; pick names from `docs/ui-style-guide.md` §6.4. No emoji as icons.
+
+## 3. teamshare-mobile-app (Expo SDK 57 + NativeWind v4)
+
+Same two-layer rule (`ui/` vendor vs `shared/` `TS*`), same zod schema
+mirroring, same `modules/<feature>/` organization. Themexing via `--ts-*`
+tokens; run `npx expo start --clear` when classes misbehave on Windows.
+
+## 4. teamshare-bridge (plain CommonJS TypeScript)
+
+- `src/lib/` = shared modules (plain exported functions + classes, named
+  exports, single quotes, JSDoc header naming the phase/IMP). `src/cli/` and
+  `src/bridge/` hold the two binaries' entry points. Custom `parseArgs`, no
+  arg libraries.
+- **Best-effort by design:** heartbeats, closing comments, streaming, config
+  writes and lock release never throw; log with `console.warn`/empty catch.
+  Only the API client propagates errors (`ApiError`), with `msg()` for logs.
+- Locks (`~/.teamshare/locks/<agentId>.lock`) gate every session; use
+  `acquireLock`/`releaseLock`; never bypass the wake queue.
+- **Gates:** `npm run build` and `npm run typecheck` — `npm run lint` is
+  broken (eslint is not installed), do not rely on it.
+
+## Cross-repo rules
+
+- Backend schema is canonical; mirrors are for UX. A stale mirror is a bug.
+- No new dependencies without a reason; prefer Node built-ins / existing libs.
+- Commit per repo, never cross-commit.
+
+## Pre-done checklist (all must pass)
+
+- [ ] Backend: `npm run build` green; eslint clean on the files you touched.
+- [ ] Backend: zod-first DTO + `ZodValidationPipe` on every new endpoint.
+- [ ] Backend: envelope + pagination + access metadata on every endpoint.
+- [ ] Frontend/mobile: imports only from `@/components/shared`; `TS*` used.
+- [ ] Frontend/mobile: `npm run build` (web) / `npx expo export` (mobile) green.
+- [ ] Bridge: `npm run build` + `npm run typecheck` green.
+- [ ] No generated files hand-edited; no secrets committed.

package/tools/usage_report.py

@@ -0,0 +1,223 @@
+#!/usr/bin/env python3
+"""
+usage_report.py - read-only agent spend report from the local opencode db.
+
+Queries ~/.local/share/opencode/opencode.db (SQLite, WAL mode, ~3.5 GB) with a
+READ-ONLY uri - never writes, never copies. Node has no built-in sqlite, so
+the teamshare-agent CLI shells out to this script (offline, no deps, stdlib
+only: sqlite3/argparse/json/datetime).
+
+Attribution rules (source of truth: the `session` table):
+  - title starting "TeamShare "        -> TeamShare bridge agent session
+  - providerID == "opencode"           -> the user's own opencode windows
+  - everything else                    -> other agent work (opencode-go, ...)
+
+Baseline (2026-08-16): $1.0445 across 14 cost-bearing sessions.
+
+Usage:
+  python usage_report.py [--day YYYY-MM-DD] [--agent <id>] [--json]
+"""
+import argparse
+import datetime
+import json
+import os
+import sqlite3
+import sys
+
+DB_PATH = os.path.join(
+    os.path.expanduser("~"), ".local", "share", "opencode", "opencode.db"
+)
+
+
+def db_uri() -> str:
+    """Read-only sqlite uri - NEVER open opencode.db for write (corruption
+    while opencode runs); NEVER copy the 3.5 GB file. Query in place."""
+    return "file:" + DB_PATH.replace("\\", "/") + "?mode=ro"
+
+
+def day_bounds(day: str) -> tuple[int, int]:
+    """Local-midnight ms-epoch bounds for a YYYY-MM-DD day."""
+    d = datetime.datetime.strptime(day, "%Y-%m-%d")
+    start = d.replace(tzinfo=datetime.datetime.now().astimezone().tzinfo)
+    end = start + datetime.timedelta(days=1)
+    return int(start.timestamp() * 1000), int(end.timestamp() * 1000)
+
+
+def parse_model(model_json: str | None) -> dict:
+    """`model` is a JSON string like {"id":..., "providerID":...}."""
+    if not model_json:
+        return {}
+    try:
+        parsed = json.loads(model_json)
+        return parsed if isinstance(parsed, dict) else {}
+    except (json.JSONDecodeError, TypeError):
+        return {}
+
+
+def attribution(title: str | None, provider_id: str | None) -> tuple[str, bool]:
+    """(label, is_teamshare): 'user' for the user's own windows, 'agent'
+    otherwise; TeamShare-titled sessions are flagged for the bridge split."""
+    if title and title.startswith("TeamShare "):
+        return "agent", True
+    if provider_id == "opencode":
+        return "user", False
+    return "agent", False
+
+
+def fmt_duration(ms: int) -> str:
+    seconds = max(0, ms) // 1000
+    if seconds < 60:
+        return f"{seconds}s"
+    minutes, sec = divmod(seconds, 60)
+    return f"{minutes}m {sec}s" if minutes < 60 else f"{minutes // 60}h {minutes % 60}m"
+
+
+def fmt_time(ms: int) -> str:
+    return datetime.datetime.fromtimestamp(ms / 1000).strftime("%H:%M")
+
+
+def run(day: str, agent: str | None, as_json: bool) -> int:
+    if not os.path.exists(DB_PATH):
+        print(
+            f"usage: opencode db not found at {DB_PATH} (has opencode ever run?)",
+            file=sys.stderr,
+        )
+        return 1
+    try:
+        con = sqlite3.connect(db_uri(), uri=True)
+    except sqlite3.Error as err:
+        print(f"usage: cannot open opencode db read-only: {err}", file=sys.stderr)
+        return 1
+
+    start_ms, end_ms = day_bounds(day)
+    try:
+        rows = con.execute(
+            "SELECT title, model, cost, tokens_input, tokens_output,"
+            " tokens_reasoning, tokens_cache_read, tokens_cache_write,"
+            " time_created, time_updated"
+            " FROM session WHERE time_created >= ? AND time_created < ?"
+            " ORDER BY time_created",
+            (start_ms, end_ms),
+        ).fetchall()
+    except sqlite3.Error as err:
+        print(f"usage: query failed: {err}", file=sys.stderr)
+        con.close()
+        return 1
+    con.close()
+
+    sessions = []
+    for (title, model_json, cost, t_in, t_out, t_reason, t_cr, t_cw,
+         created, updated) in rows:
+        cost = cost or 0.0
+        title = title or "(untitled)"
+        # Exclude opencode's "New session - ..." placeholders (empty shells
+        # that never carry a title; one even holds 547k cached tokens at
+        # $0). The baseline counts the remaining cost-bearing sessions, but
+        # REAL sessions on free models also matter for attribution - they
+        # show up at $0.0000 when they used tokens.
+        if title.startswith("New session"):
+            continue
+        if cost <= 0 and not (t_in or t_out or t_reason or t_cr or t_cw):
+            continue
+        model = parse_model(model_json)
+        provider_id = model.get("providerID") or ""
+        label, teamshare = attribution(title, provider_id)
+        sessions.append(
+            {
+                "title": title,
+                "model": model.get("id") or "",
+                "providerID": provider_id,
+                "cost": round(cost, 6),
+                "tokensInput": t_in or 0,
+                "tokensOutput": t_out or 0,
+                "tokensReasoning": t_reason or 0,
+                "tokensCacheRead": t_cr or 0,
+                "tokensCacheWrite": t_cw or 0,
+                "timeCreated": created,
+                "timeUpdated": updated,
+                "durationMin": round(max(0, (updated or created) - created) / 60000, 1),
+                "attribution": label,
+                "teamshare": teamshare,
+            }
+        )
+
+    total_cost = round(sum(s["cost"] for s in sessions), 6)
+    user_cost = round(sum(s["cost"] for s in sessions if s["attribution"] == "user"), 6)
+    agent_cost = round(total_cost - user_cost, 6)
+    teamshare_cost = round(sum(s["cost"] for s in sessions if s["teamshare"]), 6)
+
+    # --agent <id> filters to sessions whose title carries `agent <id>`
+    # (the format every bridge session now records: "TeamShare task <taskId>
+    # (agent <agentId>)").
+    if agent:
+        needle = f"agent {agent}".lower()
+        sessions = [s for s in sessions if needle in s["title"].lower()]
+        total_cost = round(sum(s["cost"] for s in sessions), 6)
+        user_cost = round(sum(s["cost"] for s in sessions if s["attribution"] == "user"), 6)
+        agent_cost = round(total_cost - user_cost, 6)
+        teamshare_cost = round(sum(s["cost"] for s in sessions if s["teamshare"]), 6)
+
+    tokens = {
+        "input": sum(s["tokensInput"] for s in sessions),
+        "output": sum(s["tokensOutput"] for s in sessions),
+        "reasoning": sum(s["tokensReasoning"] for s in sessions),
+        "cacheRead": sum(s["tokensCacheRead"] for s in sessions),
+        "cacheWrite": sum(s["tokensCacheWrite"] for s in sessions),
+    }
+
+    if as_json:
+        print(
+            json.dumps(
+                {
+                    "day": day,
+                    "dbPath": DB_PATH,
+                    "totalCost": total_cost,
+                    "sessionCount": len(sessions),
+                    "userCost": user_cost,
+                    "agentCost": agent_cost,
+                    "teamshareCost": teamshare_cost,
+                    "tokens": tokens,
+                    "sessions": sessions,
+                },
+                indent=2,
+            )
+        )
+        return 0
+
+    # Human table.
+    print(f"Agent spend report - {day} (local time)")
+    print(f"Source: {DB_PATH} (read-only)")
+    print(f"Total: ${total_cost:.4f} across {len(sessions)} sessions")
+    print(f"  user windows      : ${user_cost:.4f}")
+    print(f"  agent sessions    : ${agent_cost:.4f} (of which TeamShare ${teamshare_cost:.4f})")
+    print(f"Tokens: {tokens['input']:,} in / {tokens['output']:,} out / "
+          f"{tokens['reasoning']:,} reasoning / "
+          f"{tokens['cacheRead']:,} cache-read / {tokens['cacheWrite']:,} cache-write")
+    print()
+    print(f"{'time':<13} {'dur':<8} {'cost':<8} {'src':<8} {'model':<34} title")
+    print("-" * 110)
+    for s in sessions:
+        src = "user" if s["attribution"] == "user" else ("teamshare" if s["teamshare"] else "agent")
+        span = f"{fmt_time(s['timeCreated'])}-{fmt_time(s['timeUpdated'])}"
+        print(
+            f"{span:<13} {s['durationMin']:>4}m {s['cost']:>7.4f} {src:<8} "
+            f"{(s['providerID'] + '/' + s['model'])[:34]:<34} {s['title'][:60]}"
+        )
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Read-only opencode spend report")
+    parser.add_argument(
+        "--day",
+        default=datetime.date.today().isoformat(),
+        help="YYYY-MM-DD (default: today, local time)",
+    )
+    parser.add_argument("--agent", default=None, help="filter sessions for one agent id")
+    parser.add_argument("--json", action="store_true", help="machine-readable output")
+    args = parser.parse_args()
+    return run(args.day, args.agent, args.json)
+
+
+if __name__ == "__main__":
+    sys.exit(main())