@dev.fast/whiteboard 0.0.0-stage → 0.2.0

package/tutorial/document.json

@@ -0,0 +1,275 @@
+{
+  "title": "Whiteboard Desktop: three-minute tour",
+  "document": [
+    {
+      "type": "markdown",
+      "markdown": "# Whiteboard Desktop: three-minute tour\n"
+    },
+    {
+      "type": "section",
+      "title": "Welcome",
+      "children": [
+        {
+          "type": "markdown",
+          "markdown": "A Review is a guided, interactive explanation of a code change. The document\nkeeps the important code and system views in one place.\n"
+        },
+        {
+          "type": "tutorial",
+          "kind": "conversation",
+          "conversation": {
+            "version": 1,
+            "title": "How this Review was made",
+            "messages": [
+              {
+                "role": "user",
+                "body": "Create a Review of the feature we just worked on."
+              },
+              {
+                "role": "assistant",
+                "body": "Ok, I'm on it..."
+              }
+            ]
+          }
+        },
+        {
+          "type": "markdown",
+          "markdown": "### Your keybindings\n\nChoose your editor keys. Whiteboard highlights the active choice and uses its\nexisting extension and reload flow for Vim, Emacs, and Sublime Text.\n"
+        },
+        {
+          "type": "tutorial",
+          "kind": "keymap"
+        },
+        {
+          "type": "markdown",
+          "markdown": "### Put the keybindings to work\n\nThe editor below is live. Try hover, **Go to Definition**, or **Go to\nReferences** with the same commands you use in VS Code.\n"
+        },
+        {
+          "type": "code_peek",
+          "source": "head/src/orders/order-service.ts#L13-L29",
+          "caption": "Order service creates the order"
+        },
+        {
+          "type": "markdown",
+          "markdown": "Prose in the review also supports [links to code](review-source:head/src/orders/order-service.ts#L13-L29).\n"
+        }
+      ]
+    },
+    {
+      "type": "section",
+      "title": "Commits and diffs",
+      "children": [
+        {
+          "type": "markdown",
+          "markdown": "Whiteboard pins an exact base and head before the agent starts writing. Open\n**Commits** to see the change in author order. Expand the sample commit to see\nits files, then choose the **<>** button to inspect only that commit.\n\nThe **Diff** tab shows the complete change between the pinned base and head.\nChoose **Review** when you are ready to return to this tour.\n"
+        },
+        {
+          "type": "tutorial",
+          "kind": "view",
+          "view": "commits",
+          "label": "Explore the sample commits"
+        }
+      ]
+    },
+    {
+      "type": "section",
+      "title": "Interactive Diagrams",
+      "children": [
+        {
+          "type": "markdown",
+          "markdown": "The sequence diagram connects the checkout request to fulfillment. Select any\nmessage to open its supporting code.\n"
+        },
+        {
+          "type": "sequence",
+          "title": "Checkout to fulfillment",
+          "actors": {
+            "checkout": "Checkout API",
+            "orderService": "Order service",
+            "repository": "Orders repository",
+            "queue": "Fulfillment queue",
+            "worker": "Fulfillment worker",
+            "shipping": "Shipping gateway"
+          },
+          "steps": [
+            {
+              "type": "step",
+              "from": "checkout",
+              "to": "orderService",
+              "label": "Place order",
+              "style": "call",
+              "source": "head/src/api/checkout-api.ts#L12-L15"
+            },
+            {
+              "type": "step",
+              "from": "orderService",
+              "to": "repository",
+              "label": "Save order",
+              "style": "call",
+              "source": "head/src/orders/order-service.ts#L13-L29"
+            },
+            {
+              "type": "step",
+              "from": "repository",
+              "to": "queue",
+              "label": "Enqueue fulfillment",
+              "style": "call",
+              "source": "head/src/orders/orders-repository.ts#L9-L12"
+            },
+            {
+              "type": "step",
+              "from": "queue",
+              "to": "worker",
+              "label": "Deliver job",
+              "style": "call",
+              "source": "head/src/fulfillment/fulfillment-worker.ts#L13-L14"
+            },
+            {
+              "type": "step",
+              "from": "worker",
+              "to": "shipping",
+              "label": "Create shipment",
+              "style": "call",
+              "source": "head/src/fulfillment/fulfillment-worker.ts#L17-L19"
+            }
+          ]
+        },
+        {
+          "type": "markdown",
+          "markdown": "The database view groups writes by use case. Its operations open code too.\n"
+        },
+        {
+          "type": "database_lens",
+          "title": "Order storage",
+          "actors": {
+            "orderService": {
+              "label": "Order service",
+              "softwareMapPath": "orderService.application.orders"
+            },
+            "worker": {
+              "label": "Fulfillment worker",
+              "softwareMapPath": "orderService.fulfillment.worker"
+            }
+          },
+          "stores": {
+            "orderDatabase": {
+              "label": "Order database",
+              "storage": "relational",
+              "softwareMapPath": "orderService.data.ordersDatabase",
+              "collections": {
+                "orders": {
+                  "label": "orders",
+                  "fields": {
+                    "customerId": {
+                      "label": "customerId",
+                      "dataType": "text",
+                      "example": "customer-42"
+                    },
+                    "totalCents": {
+                      "label": "totalCents",
+                      "dataType": "integer",
+                      "example": 12500
+                    },
+                    "status": {
+                      "label": "status",
+                      "dataType": "text",
+                      "example": "fulfilled"
+                    },
+                    "createdAt": {
+                      "label": "createdAt",
+                      "dataType": "timestamp",
+                      "example": "2026-08-10T12:00:00Z"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "useCases": [
+            {
+              "label": "Create an order",
+              "operations": [
+                {
+                  "kind": "write",
+                  "store": "orderDatabase",
+                  "collection": "orders",
+                  "field": "status",
+                  "actor": "orderService",
+                  "label": "write pending order",
+                  "source": "head/src/orders/orders-repository.ts#L9-L12"
+                }
+              ]
+            },
+            {
+              "label": "Fulfill an order",
+              "operations": [
+                {
+                  "kind": "write",
+                  "store": "orderDatabase",
+                  "collection": "orders",
+                  "field": "status",
+                  "actor": "worker",
+                  "label": "write fulfilled status",
+                  "source": "head/src/fulfillment/fulfillment-worker.ts#L17-L19"
+                }
+              ]
+            }
+          ]
+        },
+        {
+          "type": "tutorial",
+          "kind": "feature",
+          "feature": "softwareMap",
+          "children": [
+            {
+              "type": "markdown",
+              "markdown": "The experimental **Map** moves from the order system to its components and\ncode. Select a node to explore the sample service.\n"
+            },
+            {
+              "type": "tutorial",
+              "kind": "view",
+              "view": "map",
+              "label": "Open the software map"
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "type": "section",
+      "title": "Agent traces",
+      "children": [
+        {
+          "type": "markdown",
+          "markdown": "Trace quotes connect a Review to the agent conversation behind a change.\nSelect this quote from an illustrative session to read it in context:\n"
+        },
+        {
+          "type": "trace_quote",
+          "traceId": "tutorial-trace",
+          "eventId": "0",
+          "text": "we want to have one shared server / source of truth for all agent chats."
+        },
+        {
+          "type": "markdown",
+          "markdown": "To capture your own sessions, open **Preferences → Settings → Experimental\nFeatures → Trace capture**. Enter your S3/R2 bucket credentials and choose\n**Enable**. Have everyone on your team do this (with the same bucket credentials) to sync and review each other's traces.\n\nTrace capture is off by default; this sample works without setup.\n"
+        }
+      ]
+    },
+    {
+      "type": "section",
+      "title": "Get help",
+      "children": [
+        {
+          "type": "markdown",
+          "markdown": "To connect Whiteboard to your agents, open **Preferences →\nSettings**. To revisit setup or take this tour again, open **Preferences →\nGetting Started**.\n"
+        }
+      ]
+    },
+    {
+      "type": "software_map",
+      "mapVersionId": "tutorial-map-base"
+    },
+    {
+      "type": "software_map",
+      "mapVersionId": "tutorial-map-head"
+    }
+  ]
+}

package/tutorial/runtime-manifest.json

@@ -0,0 +1,12 @@
+{
+  "version": 1,
+  "reviewFiles": ["document.json", "trace.json", "software-map.json"],
+  "requiredPaths": [
+    "sample-service/package.json",
+    "document.json",
+    "trace.json",
+    "software-map.json",
+    "pins.json",
+    "git-stub/HEAD"
+  ]
+}

package/tutorial/sample-service/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@dev.fast/review-tutorial-order-service",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "check": "tsc --noEmit"
+  }
+}

package/tutorial/sample-service/src/api/checkout-api.ts

@@ -0,0 +1,17 @@
+import type { OrderService } from "../orders/order-service.js";
+import type { CheckoutRequest, Order } from "../orders/order.js";
+
+export interface CheckoutResponse {
+  status: 201;
+  order: Order;
+}
+
+export class CheckoutApi {
+  constructor(private readonly orderService: OrderService) {}
+
+  checkout(request: CheckoutRequest): CheckoutResponse {
+    const order = this.orderService.placeOrder(request);
+
+    return { status: 201, order };
+  }
+}

package/tutorial/sample-service/src/app.ts

@@ -0,0 +1,26 @@
+import { CheckoutApi } from "./api/checkout-api.js";
+import { FulfillmentQueue } from "./fulfillment/fulfillment-queue.js";
+import { FulfillmentWorker } from "./fulfillment/fulfillment-worker.js";
+import { InventoryService } from "./inventory/inventory-service.js";
+import { OrderService } from "./orders/order-service.js";
+import { OrdersRepository } from "./orders/orders-repository.js";
+import { PaymentGateway } from "./payments/payment-gateway.js";
+import { ShippingGateway } from "./shipping/shipping-gateway.js";
+
+const queue = new FulfillmentQueue();
+
+const orders = new OrdersRepository(queue);
+
+const orderService = new OrderService(
+  new InventoryService(),
+  new PaymentGateway(),
+  orders,
+);
+
+export const checkoutApi = new CheckoutApi(orderService);
+
+export const fulfillmentWorker = new FulfillmentWorker(
+  queue,
+  orders,
+  new ShippingGateway(),
+);

package/tutorial/sample-service/src/database/schema.ts

@@ -0,0 +1,10 @@
+export const ordersTable = {
+  name: "orders",
+  columns: {
+    id: { type: "text", primaryKey: true },
+    customerId: { type: "text" },
+    totalCents: { type: "integer" },
+    status: { type: "text" },
+    createdAt: { type: "timestamp" },
+  },
+} as const;

package/tutorial/sample-service/src/fulfillment/fulfillment-queue.ts

@@ -0,0 +1,15 @@
+export interface FulfillmentJob {
+  orderId: string;
+}
+
+export class FulfillmentQueue {
+  private readonly jobs: FulfillmentJob[] = [];
+
+  enqueue(job: FulfillmentJob): void {
+    this.jobs.push(job);
+  }
+
+  dequeue(): FulfillmentJob | undefined {
+    return this.jobs.shift();
+  }
+}

package/tutorial/sample-service/src/fulfillment/fulfillment-worker.ts

@@ -0,0 +1,24 @@
+import type { OrdersRepository } from "../orders/orders-repository.js";
+import type { ShippingGateway } from "../shipping/shipping-gateway.js";
+import type { FulfillmentQueue } from "./fulfillment-queue.js";
+
+export class FulfillmentWorker {
+  constructor(
+    private readonly queue: FulfillmentQueue,
+    private readonly orders: OrdersRepository,
+    private readonly shipping: ShippingGateway,
+  ) {}
+
+  runNext(): string | null {
+    const job = this.queue.dequeue();
+
+    if (!job) return null;
+    const order = this.orders.find(job.orderId);
+
+    if (!order) throw new Error(`Order not found: ${job.orderId}`);
+    const shipment = this.shipping.createShipment(order);
+    this.orders.setStatus(order.id, "fulfilled");
+
+    return shipment.trackingNumber;
+  }
+}

package/tutorial/sample-service/src/inventory/inventory-service.ts

@@ -0,0 +1,11 @@
+import type { CheckoutItem } from "../orders/order.js";
+
+export class InventoryService {
+  reserve(items: readonly CheckoutItem[]): void {
+    const unavailable = items.find((item) => item.quantity < 1);
+
+    if (unavailable) {
+      throw new Error(`Invalid quantity for ${unavailable.sku}`);
+    }
+  }
+}

package/tutorial/sample-service/src/orders/order-service.ts

@@ -0,0 +1,34 @@
+import type { InventoryService } from "../inventory/inventory-service.js";
+import type { PaymentGateway } from "../payments/payment-gateway.js";
+import type { CheckoutRequest, Order } from "./order.js";
+import type { OrdersRepository } from "./orders-repository.js";
+
+export class OrderService {
+  constructor(
+    private readonly inventory: InventoryService,
+    private readonly payments: PaymentGateway,
+    private readonly orders: OrdersRepository,
+  ) {}
+
+  placeOrder(request: CheckoutRequest): Order {
+    const totalCents = request.items.reduce(
+      (sum, item) => sum + item.quantity * item.unitPriceCents,
+      0,
+    );
+
+    this.inventory.reserve(request.items);
+    this.payments.charge(request.paymentToken, totalCents);
+
+    const order: Order = {
+      id: `order-${request.customerId}`,
+      customerId: request.customerId,
+      items: request.items,
+      totalCents,
+      status: "pending",
+    };
+
+    this.orders.insert(order);
+
+    return order;
+  }
+}

package/tutorial/sample-service/src/orders/order.ts

@@ -0,0 +1,21 @@
+export type OrderStatus = "pending" | "queued" | "fulfilled";
+
+export interface CheckoutItem {
+  sku: string;
+  quantity: number;
+  unitPriceCents: number;
+}
+
+export interface Order {
+  id: string;
+  customerId: string;
+  items: readonly CheckoutItem[];
+  totalCents: number;
+  status: OrderStatus;
+}
+
+export interface CheckoutRequest {
+  customerId: string;
+  items: readonly CheckoutItem[];
+  paymentToken: string;
+}

package/tutorial/sample-service/src/orders/orders-repository.ts

@@ -0,0 +1,24 @@
+import type { FulfillmentQueue } from "../fulfillment/fulfillment-queue.js";
+import type { Order, OrderStatus } from "./order.js";
+
+export class OrdersRepository {
+  private readonly rows = new Map<string, Order>();
+
+  constructor(private readonly queue: FulfillmentQueue) {}
+
+  insert(order: Order): void {
+    this.rows.set(order.id, order);
+    this.queue.enqueue({ orderId: order.id });
+  }
+
+  find(orderId: string): Order | undefined {
+    return this.rows.get(orderId);
+  }
+
+  setStatus(orderId: string, status: OrderStatus): void {
+    const order = this.find(orderId);
+
+    if (!order) throw new Error(`Order not found: ${orderId}`);
+    this.rows.set(orderId, { ...order, status });
+  }
+}

package/tutorial/sample-service/src/payments/payment-gateway.ts

@@ -0,0 +1,12 @@
+export interface PaymentReceipt {
+  chargeId: string;
+  amountCents: number;
+}
+
+export class PaymentGateway {
+  charge(paymentToken: string, amountCents: number): PaymentReceipt {
+    if (!paymentToken) throw new Error("A payment token is required");
+
+    return { chargeId: `charge-${amountCents}`, amountCents };
+  }
+}

package/tutorial/sample-service/src/shipping/shipping-gateway.ts

@@ -0,0 +1,15 @@
+import type { Order } from "../orders/order.js";
+
+export interface Shipment {
+  trackingNumber: string;
+  orderId: string;
+}
+
+export class ShippingGateway {
+  createShipment(order: Order): Shipment {
+    return {
+      trackingNumber: `track-${order.id}`,
+      orderId: order.id,
+    };
+  }
+}

package/tutorial/sample-service/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "noEmit": true
+  },
+  "include": ["src/**/*.ts"]
+}

package/tutorial/software-map.json

@@ -0,0 +1,139 @@
+{
+  "people": {},
+  "systems": {
+    "orderService": {
+      "label": "Order service",
+      "description": "Accepts checkout requests, records orders, and completes fulfillment.",
+      "containers": {
+        "api": {
+          "label": "Checkout API",
+          "description": "Provides the typed checkout entry point.",
+          "components": {
+            "checkout": {
+              "label": "Checkout API",
+              "description": "Accepts a checkout request and delegates order creation.",
+              "coverage": {
+                "files": ["src/api/checkout-api.ts"]
+              }
+            }
+          }
+        },
+        "application": {
+          "label": "Order application",
+          "description": "Applies the rules for creating an order.",
+          "components": {
+            "orders": {
+              "label": "Order service",
+              "description": "Calculates the total, reserves stock, charges payment, and creates the order.",
+              "coverage": {
+                "files": [
+                  "src/orders/order-service.ts",
+                  "src/orders/order.ts",
+                  "src/inventory/inventory-service.ts",
+                  "src/payments/payment-gateway.ts"
+                ]
+              }
+            }
+          }
+        },
+        "data": {
+          "label": "Order data",
+          "description": "Stores orders and defines their persisted shape.",
+          "components": {
+            "ordersRepository": {
+              "label": "Orders repository",
+              "description": "Persists orders in memory and submits fulfillment jobs.",
+              "coverage": {
+                "files": ["src/orders/orders-repository.ts"]
+              }
+            },
+            "ordersDatabase": {
+              "label": "Orders table",
+              "description": "Defines the columns in the orders table.",
+              "coverage": {
+                "files": ["src/database/schema.ts"]
+              }
+            }
+          }
+        },
+        "fulfillment": {
+          "label": "Fulfillment",
+          "description": "Queues orders and runs one fulfillment job at a time.",
+          "components": {
+            "queue": {
+              "label": "Fulfillment queue",
+              "description": "Stores order identifiers until a worker can act.",
+              "coverage": {
+                "files": ["src/fulfillment/fulfillment-queue.ts"]
+              }
+            },
+            "worker": {
+              "label": "Fulfillment worker",
+              "description": "Loads a queued order, creates its shipment, and marks it fulfilled.",
+              "coverage": {
+                "files": ["src/fulfillment/fulfillment-worker.ts"]
+              }
+            }
+          }
+        },
+        "shipping": {
+          "label": "Shipping",
+          "description": "Creates shipment tracking records.",
+          "components": {
+            "gateway": {
+              "label": "Shipping gateway",
+              "description": "Creates a shipment for an order.",
+              "coverage": {
+                "files": ["src/shipping/shipping-gateway.ts"]
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "relationships": [
+    {
+      "kind": "semantic",
+      "from": "orderService.api.checkout",
+      "to": "orderService.application.orders",
+      "label": "Creates an order"
+    },
+    {
+      "kind": "semantic",
+      "from": "orderService.application.orders",
+      "to": "orderService.data.ordersRepository",
+      "label": "Stores the order"
+    },
+    {
+      "kind": "semantic",
+      "from": "orderService.data.ordersRepository",
+      "to": "orderService.data.ordersDatabase",
+      "label": "Writes an order row"
+    },
+    {
+      "kind": "semantic",
+      "from": "orderService.data.ordersRepository",
+      "to": "orderService.fulfillment.queue",
+      "label": "Enqueues the order"
+    },
+    {
+      "kind": "semantic",
+      "from": "orderService.fulfillment.queue",
+      "to": "orderService.fulfillment.worker",
+      "label": "Dispatches the job"
+    },
+    {
+      "kind": "semantic",
+      "from": "orderService.fulfillment.worker",
+      "to": "orderService.shipping.gateway",
+      "label": "Creates a shipment"
+    },
+    {
+      "kind": "semantic",
+      "from": "orderService.fulfillment.worker",
+      "to": "orderService.data.ordersRepository",
+      "label": "Marks the order fulfilled"
+    }
+  ]
+}