@huynle/hub 0.7.4 → 0.8.1

package/src/central/teams/draft-edits.ts

@@ -0,0 +1,46 @@
+// Role and policy-edge editing of a team's draft (HWA-37): small edits computed against the current draft spec (or
+// the published one) and saved through TeamStore.saveDraft, which validates the whole spec again. Nothing here
+// publishes: delivery and staffing keep using the published version until an explicit publish.
+//
+// - setRole: adds the role, or replaces the role of that name wholesale (its other fields are dropped).
+// - removeRole: drops the role and every edge touching it; the entry role cannot be removed (name another first).
+// - setEdge: replaces the edge drawn from → to (and, for a two-way edge, the one drawn to → from). An edge drawn the
+//   other way that already covers the pair is refused by the spec check (one edge per ordered pair).
+// - removeEdge: drops the edge drawn from → to, or a two-way edge drawn to → from.
+import { AgentError } from "../agent/errors"
+import type { TeamSpec } from "./validation"
+
+const isObj = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v)
+
+/** A patch replacing the roles (and edges) for saveDraft. */
+export interface DraftEdit {
+  readonly roles?: readonly unknown[]
+  readonly edges?: readonly unknown[]
+}
+
+export function setRole(spec: TeamSpec, name: string, fields: Record<string, unknown>): DraftEdit {
+  if (fields.name !== undefined && fields.name !== name) throw new AgentError("invalid", "The role's name is in the path; to rename, add the new role and remove the old one")
+  const role = { ...fields, name }
+  const at = spec.roles.findIndex((r) => r.name === name)
+  const roles = at < 0 ? [...spec.roles, role] : spec.roles.map((r, i) => (i === at ? role : r))
+  return { roles }
+}
+
+export function removeRole(spec: TeamSpec, name: string): DraftEdit {
+  if (!spec.roles.some((r) => r.name === name)) throw new AgentError("not_found", `The draft has no role ${name.slice(0, 40)}`)
+  if (spec.entryRole === name) throw new AgentError("invalid", `${name} is the entry role`, { hint: "Name another entry role first (team update entryRole)" })
+  return { roles: spec.roles.filter((r) => r.name !== name), edges: spec.edges.filter((e) => e.from !== name && e.to !== name) }
+}
+
+export function setEdge(spec: TeamSpec, edge: Record<string, unknown>): DraftEdit {
+  if (!isObj(edge) || typeof edge.from !== "string" || typeof edge.to !== "string") throw new AgentError("invalid", "An edge needs from and to (role names)")
+  const { from, to } = edge
+  const replaced = (e: TeamSpec["edges"][number]) => (e.from === from && e.to === to) || (edge.direction === "two-way" && e.from === to && e.to === from)
+  return { edges: [...spec.edges.filter((e) => !replaced(e)), edge] }
+}
+
+export function removeEdge(spec: TeamSpec, from: string, to: string): DraftEdit {
+  const drop = (e: TeamSpec["edges"][number]) => (e.from === from && e.to === to) || (e.direction === "two-way" && e.from === to && e.to === from)
+  if (!spec.edges.some(drop)) throw new AgentError("not_found", `The draft has no edge ${from.slice(0, 40)} → ${to.slice(0, 40)}`)
+  return { edges: spec.edges.filter((e) => !drop(e)) }
+}

package/src/central/teams/events.ts

@@ -0,0 +1,46 @@
+// Compact journal events of teams (HWA-33; contract TEAM_EVENT_TYPES, family `manage`). Allowlisted payloads only:
+// IDs, enums (state, change), revisions, version numbers, generations and flags. Never names, titles, descriptions,
+// role names or labels, responsibilities, tags, metadata, projects or any other definition text. The routes
+// (HWA-37) emit them after a store call succeeds; HWA-34 owns `team.denied`, HWA-36 `team.intake`.
+import type { EventInput } from "../agent/events"
+import type { TeamSeatRecord } from "./seats"
+import type { Team } from "./store"
+
+/** What a `team.updated` changed. */
+export type TeamChange = "draft" | "draft_discarded" | "published" | "paused" | "resumed"
+
+export const teamCreatedEvent = (team: Team): EventInput => ({
+  type: "team.created",
+  family: "manage",
+  subject: { teamID: team.id },
+  data: { revision: team.revision, version: team.version, state: team.state },
+})
+
+export const teamUpdatedEvent = (team: Team, change: TeamChange): EventInput => ({
+  type: "team.updated",
+  family: "manage",
+  subject: { teamID: team.id },
+  data: { change, revision: team.revision, version: team.version, paused: team.paused === true },
+})
+
+/** Archived (`state: archived`) or restored (`state: active`). */
+export const teamArchivedEvent = (team: Team): EventInput => ({
+  type: "team.archived",
+  family: "manage",
+  subject: { teamID: team.id },
+  data: { state: team.state, revision: team.revision, version: team.version },
+})
+
+export const teamStaffedEvent = (seat: TeamSeatRecord): EventInput => ({
+  type: "team.staffed",
+  family: "manage",
+  subject: { teamID: seat.teamID, staffingID: seat.id, sessionID: seat.sessionID },
+  data: { generation: seat.generation, revision: seat.revision, version: seat.teamVersion },
+})
+
+export const teamUnstaffedEvent = (seat: TeamSeatRecord): EventInput => ({
+  type: "team.unstaffed",
+  family: "manage",
+  subject: { teamID: seat.teamID, staffingID: seat.id, sessionID: seat.sessionID },
+  data: { generation: seat.generation, revision: seat.revision },
+})

package/src/central/teams/intake-routes.ts

@@ -0,0 +1,100 @@
+// Team intake routes on /api/agent (HWA-36; contract: Teams `POST /teams/:id/intake`, scope teams:submit). The rest
+// of the teams surface (definitions, staffing, roster, teams:read|manage) is HWA-37's.
+//
+//   POST /teams/:id/intake                     {title, brief?, priority?, labels?, due?, criteria?, ref?}  Idempotency-Key
+//   GET  /teams/:id/intake?status&limit&cursor → {items, cursor?}
+//   GET  /teams/:id/intake/:intake           → {intake}
+//   POST /teams/:id/intake/:intake/status    {status, expectedRevision, reason?} → {intake, assignment?}
+//
+// Who (TeamIntakeService decides the details): users; app tokens with teams:submit (submit, read and cancel their
+// own) — reads also accept teams:read/teams:manage once HWA-37 registers them; session tokens (submit under team
+// policy, entry seats report status). Another user's or an unknown team: 404 not_found. Bodies are bounded here.
+import { boundedText } from "../agent/body"
+import type { AgentContext, AgentRoute } from "../agent/routes"
+import { AgentError } from "../agent/errors"
+import { idempotencyKeyOf, storeAnswer } from "../agent/idempotency"
+import type { Store } from "../store"
+import type { TeamIntakeService } from "./intake"
+
+const PREFIX = "/api/agent/teams/:id/intake"
+const NO_STORE = { "cache-control": "no-store" }
+/** Request bodies (the brief is ≤ 16 000 characters). */
+export const INTAKE_BODY_MAX = 96 * 1024
+
+export interface IntakeRoutesDeps {
+  readonly intake: TeamIntakeService
+  readonly audit?: Pick<Store, "audit">
+}
+
+const ok = (body: unknown) => Response.json(body, { headers: NO_STORE })
+
+async function bodyOf(request: Request): Promise<Record<string, unknown>> {
+  const declared = Number(request.headers.get("content-length") ?? "0")
+  if (declared > INTAKE_BODY_MAX) throw new AgentError("invalid", `Body must be at most ${INTAKE_BODY_MAX} bytes`)
+  const text = await boundedText(request, INTAKE_BODY_MAX)
+  if (text.length > INTAKE_BODY_MAX) throw new AgentError("invalid", `Body must be at most ${INTAKE_BODY_MAX} bytes`)
+  let raw: unknown
+  try {
+    raw = JSON.parse(text === "" ? "{}" : text)
+  } catch {
+    throw new AgentError("invalid", "Body must be JSON")
+  }
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) throw new AgentError("invalid", "Body must be a JSON object")
+  return raw as Record<string, unknown>
+}
+
+function intParam(url: URL, name: string): number | undefined {
+  const raw = url.searchParams.get(name)
+  return raw === null ? undefined : /^-?[0-9]{1,12}$/.test(raw) ? Number(raw) : Number.NaN
+}
+
+export function intakeRoutes(deps: IntakeRoutesDeps): AgentRoute[] {
+  const { intake } = deps
+  const audited = async (context: AgentContext, action: string, target: string) => {
+    await deps.audit?.audit({ actor: context.user.id, action, target, detail: context.actor.kind })
+  }
+  return [
+    {
+      method: "POST",
+      path: PREFIX,
+      allow: { scope: "teams:submit", session: true },
+      async handle(context) {
+        const body = await bodyOf(context.request)
+        const key = idempotencyKeyOf(context.request)
+        const { intake: item, created } = await intake.submit(context.user.id, context.actor, context.params.id!, body, key === undefined ? {} : { idempotencyKey: key })
+        if (created) await audited(context, "team.intake.submit", item.id)
+        return storeAnswer(created, { intake: item })
+      },
+    },
+    {
+      method: "GET",
+      path: PREFIX,
+      allow: { app: true, session: true },
+      async handle({ url, user, actor, params }) {
+        const limit = intParam(url, "limit")
+        const status = url.searchParams.get("status") || undefined
+        const cursor = url.searchParams.get("cursor") || undefined
+        return ok(await intake.list(user.id, actor, params.id!, { ...(limit !== undefined ? { limit } : {}), ...(status ? { status } : {}), ...(cursor ? { cursor } : {}) }))
+      },
+    },
+    {
+      method: "GET",
+      path: `${PREFIX}/:intake`,
+      allow: { app: true, session: true },
+      async handle({ user, actor, params }) {
+        return ok({ intake: await intake.get(user.id, actor, params.id!, params.intake!) })
+      },
+    },
+    {
+      method: "POST",
+      path: `${PREFIX}/:intake/status`,
+      allow: { app: true, session: true },
+      async handle(context) {
+        const body = await bodyOf(context.request)
+        const result = await intake.setStatus(context.user.id, context.actor, context.params.id!, context.params.intake!, body)
+        await audited(context, `team.intake.${result.intake.status === "routed" ? "progress" : result.intake.status}`, result.intake.id)
+        return ok(result)
+      },
+    },
+  ]
+}