@dev.fast/whiteboard 0.2.5-preview.20261013.113 → 0.2.5-preview.20261015.115

package/tutorial/document.json

@@ -1,216 +0,0 @@
-{
-  "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 whiteboard is a guided, interactive explanation of a code change. Code,\ndiffs, and diagrams live in one document.\n"
-        },
-        {
-          "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": "### Read code like your editor\n\nThe editor below is live. Hover a symbol to see its type. **Go to\nDefinition** and **Find References** use the same keys as your editor.\n"
-        },
-        {
-          "type": "code_peek",
-          "source": "head/src/orders/order-service.ts#L13-L30",
-          "caption": "Order service creates the order"
-        }
-      ]
-    },
-    {
-      "type": "section",
-      "title": "Diffs and lenses",
-      "children": [
-        {
-          "type": "markdown",
-          "markdown": "The **Diff** tab shows the whole change between the pinned base and head.\ndiffr folds unchanged structure so you read only what moved; select a fold to\nexpand it.\n"
-        },
-        {
-          "type": "tutorial",
-          "kind": "view",
-          "view": "diff",
-          "label": "Open the diff"
-        },
-        {
-          "type": "markdown",
-          "markdown": "**Lenses** split a change into the parts that matter. Select a lens to\nfilter the diff to just those lines. Mark lines viewed and the remaining\ncounts go down.\n\nAI summaries for folded code are opt-in under **Settings → Diff display and\nAI summaries**.\n"
-        }
-      ]
-    },
-    {
-      "type": "section",
-      "title": "Interactive diagrams",
-      "children": [
-        {
-          "type": "markdown",
-          "markdown": "The sequence diagram connects the checkout request to fulfillment. Select\n**Tour** to walk it fullscreen; each message opens 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-L30"
-            },
-            {
-              "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 reads and writes by use case. Its operations open\ncode too.\n"
-        },
-        {
-          "type": "database_lens",
-          "title": "Order storage",
-          "actors": {
-            "orderService": {
-              "label": "Order service"
-            },
-            "worker": {
-              "label": "Fulfillment worker"
-            }
-          },
-          "stores": {
-            "orderDatabase": {
-              "label": "Order database",
-              "storage": "relational",
-              "collections": {
-                "orders": {
-                  "label": "orders",
-                  "fields": {
-                    "id": {
-                      "label": "id",
-                      "dataType": "text",
-                      "primaryKey": true,
-                      "example": "order-customer-42"
-                    },
-                    "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"
-                    }
-                  },
-                  "source": "head/src/database/schema.ts#L3-L9"
-                }
-              }
-            }
-          },
-          "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": "section",
-      "title": "You're all done",
-      "children": [
-        {
-          "type": "markdown",
-          "markdown": "To connect Whiteboard to your agents, open **Preferences → Settings**. To\nrevisit setup or take this tour again, open **Preferences → Getting Started**.\n"
-        }
-      ]
-    }
-  ]
-}

package/tutorial/lenses.json

@@ -1,10 +0,0 @@
-[
-  {
-    "title": "Inventory reservation",
-    "targets": [{ "kind": "files", "patterns": ["src/inventory/**"] }]
-  },
-  {
-    "title": "Payment charge",
-    "targets": [{ "kind": "files", "patterns": ["src/payments/**"] }]
-  }
-]

package/tutorial/runtime-manifest.json

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

package/tutorial/sample-service/package.json

@@ -1,9 +0,0 @@
-{
-  "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

@@ -1,17 +0,0 @@
-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

@@ -1,26 +0,0 @@
-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/drizzle-orm.d.ts

@@ -1,16 +0,0 @@
-// The sample has no dependencies; this declares the slice of drizzle-orm it uses.
-declare module "drizzle-orm/pg-core" {
-  interface Column {
-    primaryKey(): Column;
-    notNull(): Column;
-    defaultNow(): Column;
-  }
-
-  export function text(name: string): Column;
-  export function integer(name: string): Column;
-  export function timestamp(name: string): Column;
-  export function pgTable(
-    name: string,
-    columns: Record<string, Column>,
-  ): Record<string, Column>;
-}

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

@@ -1,9 +0,0 @@
-import { integer, pgTable, text, timestamp } from "drizzle-orm/pg-core";
-
-export const orders = pgTable("orders", {
-  id: text("id").primaryKey(),
-  customerId: text("customer_id").notNull(),
-  totalCents: integer("total_cents").notNull(),
-  status: text("status").notNull(),
-  createdAt: timestamp("created_at").notNull().defaultNow(),
-});

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

@@ -1,15 +0,0 @@
-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

@@ -1,24 +0,0 @@
-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/forklift-mood.ts

@@ -1,4 +0,0 @@
-/** How the forklift feels today. Do not ask it twice. */
-export type ForkliftMood = "contemplative" | "grumpy" | "suspiciously cheerful";
-
-export const FORKLIFT_MOOD: ForkliftMood = "contemplative";

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

@@ -1,28 +0,0 @@
-import type { CheckoutItem, Sku } from "../orders/order.js";
-import { FORKLIFT_MOOD } from "./forklift-mood.js";
-import { blameTheGremlins, countShelvesTwice } from "./warehouse-lore.js";
-
-export class InventoryService {
-  private readonly held = new Map<string, number>();
-
-  reserve(items: readonly CheckoutItem[]): void {
-    const unavailable = items.find((item) => item.quantity < 1);
-
-    if (unavailable) {
-      throw new Error(`Invalid quantity for ${unavailable.sku}`);
-    }
-  }
-
-  release(items: readonly CheckoutItem[]): void {
-    for (const item of items) {
-      this.held.delete(item.sku);
-    }
-  }
-
-  /** How sure the warehouse is about a shelf, given the forklift's mood. */
-  audit(sku: Sku): string {
-    if (countShelvesTwice(sku) === 0) return blameTheGremlins(sku);
-
-    return `${sku} was counted while the forklift felt ${FORKLIFT_MOOD}`;
-  }
-}

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

@@ -1,11 +0,0 @@
-import type { Sku } from "../orders/order.js";
-
-/** Every shelf is counted twice, because the first count is always wrong. */
-export function countShelvesTwice(sku: Sku): number {
-  return sku.length * 2;
-}
-
-/** When stock goes missing, it was them. */
-export function blameTheGremlins(sku: Sku): string {
-  return `Gremlins took the last ${sku}`;
-}

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

@@ -1,35 +0,0 @@
-import type { InventoryService } from "../inventory/inventory-service.js";
-import type { PaymentGateway } from "../payments/payment-gateway.js";
-import type { Cents, 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,
-  ) {}
-
-  /** Reserves the stock, charges the customer, and saves a pending order. */
-  placeOrder(request: CheckoutRequest): Order {
-    const totalCents: Cents = 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

@@ -1,43 +0,0 @@
-/** Where an order is in its short, eventful life. */
-export type OrderStatus =
-  /** Charged, but still in the building. */
-  | "pending"
-  /** Waiting its turn on the fulfillment queue. */
-  | "queued"
-  /** Out the door. Regret is not a refund reason. */
-  | "fulfilled";
-
-/** A stock-keeping unit, like `SKU-RUBBER-DUCK`. */
-export type Sku = `SKU-${string}`;
-
-/** Money in whole cents, because floats cannot be trusted with money. */
-export type Cents = number;
-
-/** One line of a cart. */
-export interface CheckoutItem {
-  /** What the customer wants. */
-  sku: Sku;
-  /** How many they want. Zero is a cry for help. */
-  quantity: number;
-  /** The price of one unit, before the payment gateway takes its cut. */
-  unitPriceCents: Cents;
-}
-
-/** An order the service has accepted and charged for. */
-export interface Order {
-  /** Derived from the customer, so each customer gets one order. Allegedly. */
-  id: `order-${string}`;
-  customerId: string;
-  items: readonly CheckoutItem[];
-  /** Every line's quantity times its unit price, in cents. */
-  totalCents: Cents;
-  status: OrderStatus;
-}
-
-/** What the checkout API hands the order service. */
-export interface CheckoutRequest {
-  customerId: string;
-  items: readonly CheckoutItem[];
-  /** An opaque token from the payment provider. Never log it. */
-  paymentToken: string;
-}

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

@@ -1,24 +0,0 @@
-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/fraud-vibes.ts

@@ -1,4 +0,0 @@
-/** A fraud score derived entirely from vibes: 0 is chill, 1 is not. */
-export function vibeCheck(paymentToken: string): number {
-  return paymentToken.startsWith("tok_sus") ? 1 : 0;
-}

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

@@ -1,29 +0,0 @@
-import type { Cents } from "../orders/order.js";
-import { vibeCheck } from "./fraud-vibes.js";
-import { RACCOON_ON_DUTY, nervouslyRound } from "./raccoon-ledger.js";
-
-export interface PaymentReceipt {
-  chargeId: string;
-  amountCents: Cents;
-  /** Who signed off on the charge. */
-  approvedBy: typeof RACCOON_ON_DUTY;
-}
-
-export class PaymentGateway {
-  charge(paymentToken: string, amountCents: number): PaymentReceipt {
-    if (!paymentToken) throw new Error("A payment token is required");
-
-    return {
-      chargeId: `charge-${amountCents}`,
-      amountCents,
-      approvedBy: RACCOON_ON_DUTY,
-    };
-  }
-
-  /** Refunds a receipt, provided the vibes allow it. */
-  refund(receipt: PaymentReceipt, paymentToken: string): Cents {
-    if (vibeCheck(paymentToken) > 0.5) return 0;
-
-    return nervouslyRound(receipt.amountCents);
-  }
-}

package/tutorial/sample-service/src/payments/raccoon-ledger.ts

@@ -1,9 +0,0 @@
-import type { Cents } from "../orders/order.js";
-
-/** The ledger is kept by a raccoon. It has never been audited. */
-export const RACCOON_ON_DUTY = "Gerald";
-
-/** Rounds to the nearest cent, then rounds again out of anxiety. */
-export function nervouslyRound(cents: Cents): Cents {
-  return Math.round(Math.round(cents));
-}

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

@@ -1,15 +0,0 @@
-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

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