create-substrat 0.0.1 → 0.1.1

package/template/src/module.ts

@@ -0,0 +1,297 @@
+import {
+  addDecimal,
+  compareDecimal,
+  moneyOf,
+  mulMoney,
+  z,
+  type EntityRef,
+  type Money,
+} from '@substrat-run/contracts';
+import {
+  assertAllowed,
+  ulid,
+  type ModuleRegistration,
+  type OperationHandler,
+} from '@substrat-run/kernel';
+import {
+  closeWorkOrder,
+  completeWorkOrder,
+  createWorkOrder,
+  getReportedLines,
+  listOrders,
+  PERM as WO,
+  type BillableLine,
+  type WorkOrder,
+} from '@substrat-run/engine-workorder';
+import { bikeShopManifest, SHOP_PERM } from './manifest.js';
+import { bikeShopMigrations } from './migrations.js';
+
+// ============================================================================
+// The bike-shop operations. Each is either:
+//   - a thin custodian of the vertical's own tables (customers, bikes, prices),
+//     OR
+//   - a COMPOSITION that wraps an engine's in-scope function inside the same
+//     transaction and adds the vertical's policy (the pricing moment).
+//
+// Every operation's FIRST line is the permission check. Data access is
+// `ctx.sql` only. No `fetch`, no `node:*`, no other engine's tables.
+// ============================================================================
+
+export interface CustomerRow {
+  id: string;
+  number: string;
+  name: string;
+  phone: string | null;
+  created_at: string;
+}
+
+export interface BikeRow {
+  id: string;
+  customer_id: string;
+  label: string;
+  frame_no: string | null;
+  created_at: string;
+}
+
+export interface PriceRow {
+  article: string;
+  description: string;
+  unit: string;
+  price_amount: string;
+  currency: string;
+  min_qty: string | null;
+  internal: number;
+}
+
+const createCustomerOp: OperationHandler<
+  { number: string; name: string; phone?: string },
+  CustomerRow
+> = async (ctx, input) => {
+  assertAllowed(await ctx.check(SHOP_PERM.customerManage));
+  const id = ulid();
+  ctx.sql.exec(
+    `INSERT INTO shop_customers (id, number, name, phone, created_at) VALUES (?, ?, ?, ?, ?)`,
+    [id, input.number, input.name, input.phone ?? null, new Date().toISOString()],
+  );
+  return ctx.sql.query<CustomerRow>('SELECT * FROM shop_customers WHERE id = ?', [id])[0]!;
+};
+
+const listCustomersOp: OperationHandler<undefined, (CustomerRow & { bikes: BikeRow[] })[]> = async (
+  ctx,
+) => {
+  assertAllowed(await ctx.check(SHOP_PERM.customerManage));
+  const customers = ctx.sql.query<CustomerRow>('SELECT * FROM shop_customers ORDER BY number');
+  return customers.map((c) => ({
+    ...c,
+    bikes: ctx.sql.query<BikeRow>('SELECT * FROM shop_bikes WHERE customer_id = ? ORDER BY label', [
+      c.id,
+    ]),
+  }));
+};
+
+const registerBikeOp: OperationHandler<
+  { customerId: string; label: string; frameNo?: string },
+  BikeRow
+> = async (ctx, input) => {
+  assertAllowed(await ctx.check(SHOP_PERM.bikeManage));
+  const customer = ctx.sql.query<CustomerRow>('SELECT * FROM shop_customers WHERE id = ?', [
+    input.customerId,
+  ])[0];
+  if (!customer) throw new Error(`customer not found: ${input.customerId}`);
+  const id = ulid();
+  ctx.sql.exec(
+    `INSERT INTO shop_bikes (id, customer_id, label, frame_no, created_at) VALUES (?, ?, ?, ?, ?)`,
+    [id, customer.id, input.label, input.frameNo ?? null, new Date().toISOString()],
+  );
+  // Record the bike → customer edge the manifest declared, so the portal walk
+  // (workorder → bike → customer) can resolve an entity-narrowed grant.
+  ctx.link({ entityType: 'bike', entityId: id }, { entityType: 'customer', entityId: customer.id });
+  return ctx.sql.query<BikeRow>('SELECT * FROM shop_bikes WHERE id = ?', [id])[0]!;
+};
+
+const upsertPriceOp: OperationHandler<
+  {
+    article: string;
+    description: string;
+    unit: string;
+    priceAmount: string;
+    currency?: string;
+    minQty?: string;
+    internal?: boolean;
+  },
+  PriceRow
+> = async (ctx, input) => {
+  assertAllowed(await ctx.check(SHOP_PERM.customerManage));
+  ctx.sql.exec(
+    `INSERT OR REPLACE INTO shop_price_list
+       (article, description, unit, price_amount, currency, min_qty, internal)
+     VALUES (?, ?, ?, ?, ?, ?, ?)`,
+    [
+      input.article,
+      input.description,
+      input.unit,
+      input.priceAmount,
+      input.currency ?? 'SEK',
+      input.minQty ?? null,
+      input.internal ? 1 : 0,
+    ],
+  );
+  return ctx.sql.query<PriceRow>('SELECT * FROM shop_price_list WHERE article = ?', [
+    input.article,
+  ])[0]!;
+};
+
+const priceListOp: OperationHandler<undefined, PriceRow[]> = async (ctx) => {
+  assertAllowed(await ctx.check(SHOP_PERM.customerManage));
+  return ctx.sql.query<PriceRow>('SELECT * FROM shop_price_list ORDER BY article');
+};
+
+/**
+ * Open a repair: a vertical operation that composes the engine's `createWorkOrder`.
+ * The vertical resolves its own vocabulary (a bike, its owner) into the engine's
+ * `facility`/`customer` refs; the engine owns the number, the state, the event.
+ */
+const createRepairOp: OperationHandler<
+  { bikeId: string; kind: string; title: string; description?: string },
+  WorkOrder
+> = async (ctx, input) => {
+  assertAllowed(await ctx.check(WO.create));
+  const bike = ctx.sql.query<BikeRow>('SELECT * FROM shop_bikes WHERE id = ?', [input.bikeId])[0];
+  if (!bike) throw new Error(`bike not found: ${input.bikeId}`);
+  return createWorkOrder(ctx, {
+    facility: { entityType: 'bike', entityId: bike.id },
+    customer: { entityType: 'customer', entityId: bike.customer_id },
+    kind: input.kind,
+    title: input.title,
+    ...(input.description !== undefined ? { description: input.description } : {}),
+  });
+};
+
+/**
+ * THE PRICING MOMENT — the whole reason a vertical exists. Read the engine's
+ * reported time and material, price them against the vertical's OWN price list
+ * (labor bills at least its minimum quantity; internal articles are dropped),
+ * then hand the priced lines back to the engine's `completeWorkOrder`. One
+ * transaction: the engine's invariant stays intact and pricing is 100% vertical.
+ * The engine's `workorder.completed` event carries these lines, and the
+ * invoicing engine consumes it — no import between the two.
+ */
+const completeRepairOp: OperationHandler<
+  { orderId: string },
+  { order: WorkOrder; billable: BillableLine[]; total: Money }
+> = async (ctx, input) => {
+  assertAllowed(await ctx.check(WO.complete));
+  const reported = getReportedLines(ctx, input.orderId);
+  const prices = new Map<string, PriceRow>(
+    ctx.sql.query<PriceRow>('SELECT * FROM shop_price_list').map((p) => [p.article, p]),
+  );
+
+  const billable: BillableLine[] = [];
+
+  // Labor: sum reported hours, then bill at least the minimum quantity.
+  const laborPrice = prices.get('labor');
+  const reportedHours = reported.time.reduce((sum, t) => addDecimal(sum, t.hours), '0');
+  if (laborPrice && compareDecimal(reportedHours, '0') > 0) {
+    const minQty = laborPrice.min_qty ?? '0';
+    const qty = compareDecimal(reportedHours, minQty) >= 0 ? reportedHours : minQty;
+    const unitPrice = moneyOf(laborPrice.price_amount, laborPrice.currency);
+    billable.push({
+      article: 'labor',
+      description: laborPrice.description,
+      qty,
+      unit: laborPrice.unit,
+      unitPrice,
+      lineTotal: mulMoney(qty, unitPrice),
+      sourceType: 'time',
+      sourceId: input.orderId,
+    });
+  }
+
+  // Parts: one billable line per reported material; internal articles dropped.
+  for (const m of reported.material) {
+    const price = prices.get(m.article);
+    if (!price) throw new Error(`no price for article: ${m.article}`);
+    if (price.internal) continue;
+    const unitPrice = moneyOf(price.price_amount, price.currency);
+    billable.push({
+      article: m.article,
+      description: price.description,
+      qty: m.qty,
+      unit: price.unit,
+      unitPrice,
+      lineTotal: mulMoney(m.qty, unitPrice),
+      sourceType: 'material',
+      sourceId: m.id,
+    });
+  }
+
+  const result = completeWorkOrder(ctx, { orderId: input.orderId, billable });
+  return { order: result.order, billable, total: result.total };
+};
+
+/**
+ * Pickup: hand the bike back (completed → closed). A thin composition of the
+ * engine's in-scope `closeWorkOrder`; the vertical owns the vocabulary
+ * ("pickup"), the engine owns the transition.
+ */
+const closeRepairOp: OperationHandler<{ orderId: string }, WorkOrder> = async (ctx, input) => {
+  assertAllowed(await ctx.check(WO.close));
+  return closeWorkOrder(ctx, { orderId: input.orderId });
+};
+
+/**
+ * The customer PORTAL listing. A proof walk: no blanket `workorder:read`, one
+ * PER-ENTITY check per repair. A portal customer holds an entity-narrowed grant
+ * on their own customer record, so the walk workorder → bike → customer lets
+ * them through for their own repairs and no one else's.
+ */
+const portalRepairsOp: OperationHandler<undefined, WorkOrder[]> = async (ctx) => {
+  const visible: WorkOrder[] = [];
+  for (const order of listOrders(ctx)) {
+    const decision = await ctx.check(WO.read, { entityType: 'workorder', entityId: order.id });
+    if (decision.allowed) visible.push(order);
+  }
+  return visible;
+};
+
+const timelineInput = z.object({
+  entityType: z.string().min(1),
+  entityId: z.string().min(1),
+});
+
+/**
+ * An entity's event timeline, read straight off the spine (a read of `_substrat_*`
+ * for a projection is allowed; writing it is not). Gated by a per-entity
+ * `workorder:read` check, so it obeys the same walk as the portal.
+ */
+const timelineOp: OperationHandler<
+  z.infer<typeof timelineInput>,
+  { type: string; occurred_at: string; actor: string }[]
+> = async (ctx, rawInput) => {
+  const entity: EntityRef = timelineInput.parse(rawInput);
+  assertAllowed(await ctx.check(WO.read, entity));
+  // Append order is authoritative — rowid, not ULID (ids minted in the same
+  // millisecond are not mutually ordered).
+  return ctx.sql.query(
+    `SELECT type, occurred_at, actor FROM _substrat_outbox
+     WHERE entity_type = ? AND entity_id = ? ORDER BY rowid`,
+    [entity.entityType, entity.entityId],
+  );
+};
+
+export const bikeShopModule: ModuleRegistration = {
+  manifest: bikeShopManifest,
+  migrations: bikeShopMigrations,
+  operations: {
+    'shop/create-customer': createCustomerOp as never,
+    'shop/list-customers': listCustomersOp as never,
+    'shop/register-bike': registerBikeOp as never,
+    'shop/upsert-price': upsertPriceOp as never,
+    'shop/price-list': priceListOp as never,
+    'shop/create-repair': createRepairOp as never,
+    'shop/complete-repair': completeRepairOp as never,
+    'shop/close-repair': closeRepairOp as never,
+    'shop/portal-repairs': portalRepairsOp as never,
+    'shop/timeline': timelineOp as never,
+  },
+};

package/template/src/seed.ts

@@ -0,0 +1,265 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  platformActorId,
+  principalId,
+  scopeId,
+  tenantId,
+  type PermissionKey,
+  type PrincipalId,
+  type RoleDefinition,
+  type ScopeId,
+  type TenantId,
+} from '@substrat-run/contracts';
+import { ulid } from '@substrat-run/kernel';
+import { SqliteScopeHost } from '@substrat-run/adapter-sqlite';
+import { workorderModule, PERM as WO } from '@substrat-run/engine-workorder';
+import { invoicingModule, INVOICING_PERM as INV } from '@substrat-run/engine-invoicing';
+import { bikeShopModule } from './module.js';
+import { SHOP_PERM } from './manifest.js';
+
+// ============================================================================
+// The seeded world. TWO tenants on purpose: the first is the shop the scenario
+// exercises; the second exists only so the scenario can watch the tenant
+// boundary turn its admin away when he reaches across (a cross-tenant attacker
+// is the cheapest possible proof that isolation is real).
+// ============================================================================
+
+export interface BikeShopWorld {
+  t1: TenantId; // the shop under test
+  s1: ScopeId; //   its workshop scope
+  t2: TenantId; // a second, unrelated shop
+  s2: ScopeId; //   its workshop scope
+  greta: PrincipalId; // workshop-admin @ t1
+  mans: PrincipalId; // mechanic @ t1
+  lisbeth: PrincipalId; // portal customer @ t1 (owns a bike)
+  otto: PrincipalId; // portal customer @ t1 (owns a different bike)
+  rutger: PrincipalId; // workshop-admin @ t2 — the cross-tenant attacker
+  lisbethId: string; // customer record ids (filled on first seed)
+  ottoId: string;
+  crescentId: string; // Lisbeth's bike
+  bianchiId: string; // Otto's bike
+}
+
+/**
+ * The modules this vertical composes, in registration order. Exported so the
+ * permission checkpoint (`pnpm lint:permissions`) renders from the same array
+ * the running host registers — the artifact can never drift from reality.
+ */
+export const MODULES = [workorderModule, invoicingModule, bikeShopModule];
+
+const adminPerms: PermissionKey[] = [
+  SHOP_PERM.customerManage,
+  SHOP_PERM.bikeManage,
+  WO.create,
+  WO.read,
+  WO.assign,
+  WO.report,
+  WO.complete,
+  WO.close,
+  INV.read,
+  INV.export,
+];
+
+/**
+ * This vertical's role table — identical in every tenant, so it is a plain
+ * constant the permission snapshot can render without naming a tenant. Exported
+ * for the same reason as MODULES.
+ */
+export const ROLES: RoleDefinition[] = [
+  { key: 'workshop-admin', permissions: adminPerms, source: 'vertical' },
+  { key: 'mechanic', permissions: [WO.read, WO.report], source: 'vertical' },
+];
+
+/** What a portal customer receives, narrowed to their own customer record. */
+const portalPerms: PermissionKey[] = [WO.read];
+
+/**
+ * Entity-narrowed grant SHAPES. The grants themselves are per-principal and
+ * minted at runtime, so they can never be a build artifact; their shape is what
+ * tells a reviewer which keys are reachable outside the role table.
+ */
+export const ENTITY_GRANTS: { entityType: string; permissions: PermissionKey[] }[] = [
+  { entityType: 'customer', permissions: portalPerms },
+];
+
+export function buildBikeShopHost(dir: string): SqliteScopeHost {
+  const host = new SqliteScopeHost({ dir });
+  for (const m of MODULES) host.registerModule(m);
+  return host;
+}
+
+/**
+ * Provision ONE tenant of this vertical: tenant, entitlements for every module
+ * it runs, an active scope, the role table, and the owner holding workshop-admin.
+ * This is what an instantiate button would call — no demo cast, no fixtures.
+ */
+async function provisionShop(
+  host: SqliteScopeHost,
+  input: { tenantId: TenantId; scopeId: ScopeId; owner: PrincipalId; slug: string; name: string },
+): Promise<void> {
+  const staff = platformActorId.parse(ulid());
+  await host.admin.createTenant(staff, { id: input.tenantId, slug: input.slug, name: input.name });
+  // Entitlements are default-deny: the SKU flag for each module this vertical
+  // runs must be granted before any of its operations resolve.
+  for (const key of ['workorder', 'invoicing', 'bikeshop']) {
+    await host.admin.grantEntitlement(staff, input.tenantId, key);
+  }
+  await host.provisionScope(staff, {
+    tenantId: input.tenantId,
+    scopeId: input.scopeId,
+    jurisdiction: 'global',
+  });
+  // Provisioning writes the scope as `provisioning`; nothing may use it until it
+  // is active (here the platform and the vertical are one process, so the
+  // confirmation is immediate).
+  await host.admin.activateScope(staff, input.tenantId, input.scopeId);
+  for (const role of ROLES) await host.admin.defineRole(staff, input.tenantId, role);
+  await host.admin.assignRole(staff, {
+    principalId: input.owner,
+    roleKey: 'workshop-admin',
+    node: { tenantId: input.tenantId, scopeId: null },
+  });
+}
+
+/**
+ * Idempotent seed. Everything that mutates the control plane runs only on a
+ * FRESH data dir (guarded by cast.json); on restart the tenants, roles, grants
+ * and entities are already in the SQLite files, so we just rebuild the handle
+ * object. Safe to call on every server start and on every test.
+ */
+export async function seedBikeShop(host: SqliteScopeHost, dir: string): Promise<BikeShopWorld> {
+  const castPath = join(dir, 'cast.json');
+  if (existsSync(castPath)) {
+    const raw = JSON.parse(readFileSync(castPath, 'utf8')) as Record<string, string>;
+    return {
+      t1: tenantId.parse(raw.t1),
+      s1: scopeId.parse(raw.s1),
+      t2: tenantId.parse(raw.t2),
+      s2: scopeId.parse(raw.s2),
+      greta: principalId.parse(raw.greta),
+      mans: principalId.parse(raw.mans),
+      lisbeth: principalId.parse(raw.lisbeth),
+      otto: principalId.parse(raw.otto),
+      rutger: principalId.parse(raw.rutger),
+      lisbethId: raw.lisbethId!,
+      ottoId: raw.ottoId!,
+      crescentId: raw.crescentId!,
+      bianchiId: raw.bianchiId!,
+    };
+  }
+
+  const staff = platformActorId.parse(ulid());
+  const world: BikeShopWorld = {
+    t1: tenantId.parse(ulid()),
+    s1: scopeId.parse(ulid()),
+    t2: tenantId.parse(ulid()),
+    s2: scopeId.parse(ulid()),
+    greta: principalId.parse(ulid()),
+    mans: principalId.parse(ulid()),
+    lisbeth: principalId.parse(ulid()),
+    otto: principalId.parse(ulid()),
+    rutger: principalId.parse(ulid()),
+    lisbethId: '',
+    ottoId: '',
+    crescentId: '',
+    bianchiId: '',
+  };
+
+  // The shop under test, and a second unrelated shop whose admin will attack it.
+  await provisionShop(host, {
+    tenantId: world.t1,
+    scopeId: world.s1,
+    owner: world.greta,
+    slug: 'kedja-kugghjul',
+    name: 'Kedja & Kugghjul Cykelverkstad',
+  });
+  await provisionShop(host, {
+    tenantId: world.t2,
+    scopeId: world.s2,
+    owner: world.rutger,
+    slug: 'trampolin',
+    name: 'Trampolin Cykel',
+  });
+
+  // The rest of t1's cast.
+  await host.admin.assignRole(staff, {
+    principalId: world.mans,
+    roleKey: 'mechanic',
+    node: { tenantId: world.t1, scopeId: world.s1 },
+  });
+
+  // Seed entities go through the operations (NEVER raw SQL): the seed exercises
+  // the same permission checks and event spine the app does.
+  const greta = await host.getScope(world.greta, world.t1, world.s1);
+  const lisbethCustomer = await greta.invoke<{ id: string }>('shop/create-customer', {
+    number: '2001',
+    name: 'Lisbeth Sandell',
+    phone: '070-123 45 67',
+  });
+  const ottoCustomer = await greta.invoke<{ id: string }>('shop/create-customer', {
+    number: '2002',
+    name: 'Otto Vinge',
+  });
+  const crescent = await greta.invoke<{ id: string }>('shop/register-bike', {
+    customerId: lisbethCustomer.id,
+    label: 'Crescent Elina 3-vxl',
+    frameNo: 'CR-88412',
+  });
+  const bianchi = await greta.invoke<{ id: string }>('shop/register-bike', {
+    customerId: ottoCustomer.id,
+    label: 'Bianchi Oltre XR3',
+  });
+  await greta.invoke('shop/upsert-price', {
+    article: 'labor',
+    description: 'Mechanic time',
+    unit: 'hour',
+    priceAmount: '495',
+    minQty: '0.5',
+  });
+  await greta.invoke('shop/upsert-price', {
+    article: 'shop-supplies',
+    description: 'Workshop supplies',
+    unit: 'ea',
+    priceAmount: '15',
+    internal: true,
+  });
+  await greta.invoke('shop/upsert-price', {
+    article: 'tube-28',
+    description: 'Inner tube 28"',
+    unit: 'ea',
+    priceAmount: '89',
+  });
+  await greta.invoke('shop/upsert-price', {
+    article: 'chain-9s',
+    description: 'Chain, 9-speed',
+    unit: 'ea',
+    priceAmount: '249',
+  });
+
+  world.lisbethId = lisbethCustomer.id;
+  world.ottoId = ottoCustomer.id;
+  world.crescentId = crescent.id;
+  world.bianchiId = bianchi.id;
+
+  // Portal grants: entity-narrowed per customer (ENTITY_GRANTS). Lisbeth and
+  // Otto each hold workorder:read on their OWN customer record only — the walk
+  // workorder → bike → customer does the rest.
+  for (const [principal, customerId] of [
+    [world.lisbeth, world.lisbethId],
+    [world.otto, world.ottoId],
+  ] as const) {
+    for (const permission of portalPerms) {
+      await host.admin.grant(staff, {
+        principalId: principal,
+        permission,
+        node: { tenantId: world.t1, scopeId: world.s1 },
+        entity: { entityType: 'customer', entityId: customerId },
+        grantedBy: world.greta,
+      });
+    }
+  }
+
+  writeFileSync(castPath, JSON.stringify(world, null, 2));
+  return world;
+}