@kelpie/server 0.11.0 → 0.13.0

package/src/modules/workspace/service.ts

@@ -21,10 +21,12 @@ import { seedStarterForms } from './seedStarterForms.ts'
 import { parseInvitableRole, parseMemberRole, roleAllows } from './roles.ts'
 import type { InvitableRole, InviteStatus, MemberRole } from './roles.ts'
 import {
-  STARTER_HANDBOOK_PAGES,
+  getHandbookPagesForTemplate,
+  isStarterHandbookBody,
   STARTER_PIPELINE_STAGES,
   starterHandbookBody,
 } from './starters.ts'
+import type { HandbookTemplateId } from './starters.ts'
 
 /**
  * Workspaces and who belongs to them.
@@ -89,6 +91,15 @@ export interface CreateWorkspaceInput {
   readonly timezone: string
 }
 
+export interface SeedHandbookInput {
+  readonly handbookTemplate: HandbookTemplateId
+  readonly replace?: boolean | undefined
+}
+
+export interface SeedHandbookResult {
+  readonly handbookPages: number
+}
+
 /**
  * A partial update, on `api.md`'s rule: an absent field is not being changed,
  * and `null` clears one.
@@ -108,6 +119,8 @@ export interface UpdateWorkspaceInput {
 export interface WorkspaceService {
   /** Creates the workspace, makes the caller its owner, and seeds its starters. */
   create(actor: SessionActor, input: CreateWorkspaceInput): Promise<WorkspaceView>
+  /** Seeds starter handbook pages for the chosen organisation template. */
+  seedHandbook(actor: Actor, workspaceId: string, input: SeedHandbookInput): Promise<SeedHandbookResult>
   get(actor: Actor, workspaceId: string): Promise<WorkspaceView>
   update(actor: Actor, workspaceId: string, changes: UpdateWorkspaceInput): Promise<WorkspaceView>
   /**
@@ -439,19 +452,6 @@ export function createWorkspaceService(dependencies: WorkspaceDependencies): Wor
           joinedAt: now,
         })
 
-        await repository.insertHandbookPages(
-          tx,
-          STARTER_HANDBOOK_PAGES.map((page, index) => ({
-            id: dependencies.createId('handbookPage'),
-            workspaceId,
-            title: page.title,
-            slug: page.slug,
-            sortOrder: index,
-            body: starterHandbookBody(page.title),
-            updatedBy: memberId,
-          })),
-        )
-
         await repository.insertPipelineStages(
           tx,
           Object.entries(STARTER_PIPELINE_STAGES).flatMap(([kind, stages]) =>
@@ -511,6 +511,51 @@ export function createWorkspaceService(dependencies: WorkspaceDependencies): Wor
       }, { workspaceId, actor: toEventActor(actor) })
     },
 
+    async seedHandbook(actor, workspaceId, input) {
+      const { memberId } = await requireMembership(actor, workspaceId, 'admin')
+
+      if (memberId === null) {
+        throw new AppError('forbidden', 'This action needs a workspace member')
+      }
+
+      const existing = await repository.listHandbookPages(dependencies.db, workspaceId)
+
+      if (existing.length > 0) {
+        if (input.replace !== true) {
+          throw AppError.conflict('This workspace already has handbook pages', [
+            { field: 'replace', message: 'Set replace to true to replace starter pages' },
+          ])
+        }
+
+        if (!existing.every((page) => isStarterHandbookBody(page))) {
+          throw AppError.conflict('Handbook pages have been edited and cannot be replaced')
+        }
+      }
+
+      const templatePages = getHandbookPagesForTemplate(input.handbookTemplate)
+
+      return dependencies.transaction(async ({ tx }) => {
+        if (existing.length > 0) {
+          await repository.deleteAllHandbookPages(tx, workspaceId)
+        }
+
+        await repository.insertHandbookPages(
+          tx,
+          templatePages.map((page, index) => ({
+            id: dependencies.createId('handbookPage'),
+            workspaceId,
+            title: page.title,
+            slug: page.slug,
+            sortOrder: index,
+            body: starterHandbookBody(page),
+            updatedBy: memberId,
+          })),
+        )
+
+        return { handbookPages: templatePages.length }
+      })
+    },
+
     async get(actor, workspaceId) {
       await requireMembership(actor, workspaceId, 'member')
       const workspace = await repository.findWorkspace(dependencies.db, workspaceId)

package/src/modules/workspace/starters.ts

@@ -6,27 +6,288 @@
  * owner can then rename, reorder, or delete.
  */
 
+export const HANDBOOK_TEMPLATE_IDS = [
+  'startup',
+  'agency',
+  'nonprofit',
+  'community',
+  'professional-services',
+  'creator',
+] as const
+
+export type HandbookTemplateId = (typeof HANDBOOK_TEMPLATE_IDS)[number]
+
 export interface StarterHandbookPage {
   readonly title: string
   readonly slug: string
+  readonly bodyPrompt: string
+}
+
+export interface HandbookTemplate {
+  readonly id: HandbookTemplateId
+  readonly label: string
+  readonly description: string
+  readonly pages: readonly StarterHandbookPage[]
+}
+
+function page(title: string, slug: string, bodyPrompt: string): StarterHandbookPage {
+  return { title, slug, bodyPrompt }
 }
 
-/** Bodies start as stubs. Teams write them; agents read whatever is there. */
-export const STARTER_HANDBOOK_PAGES: readonly StarterHandbookPage[] = [
-  { title: 'About us', slug: 'about-us' },
-  { title: 'Product', slug: 'product' },
-  { title: 'Ideal customer profile', slug: 'ideal-customer-profile' },
-  { title: 'Voice and tone', slug: 'voice-and-tone' },
-  { title: 'Pricing', slug: 'pricing' },
-  { title: 'How we sell', slug: 'how-we-sell' },
-  { title: 'Competitive landscape', slug: 'competitive-landscape' },
-  { title: 'Team and roles', slug: 'team-and-roles' },
-  { title: 'Tools and stack', slug: 'tools-and-stack' },
-  { title: 'Agent FAQ', slug: 'agent-faq' },
+const STARTUP_PAGES: readonly StarterHandbookPage[] = [
+  page('About us', 'about-us', 'What does your company do, and why does it exist?'),
+  page('Product', 'product', 'What do you sell, and what problem does it solve?'),
+  page(
+    'Ideal customer profile',
+    'ideal-customer-profile',
+    'Who is your best-fit customer? Size, industry, pain points, and buying signals.',
+  ),
+  page('Voice and tone', 'voice-and-tone', 'How should Kelpie and your agents sound when they write on your behalf?'),
+  page('Pricing', 'pricing', 'How is your product priced? Plans, tiers, and what is included.'),
+  page('How we sell', 'how-we-sell', 'Your sales motion: inbound, outbound, trials, demos, and typical cycle.'),
+  page(
+    'Competitive landscape',
+    'competitive-landscape',
+    'Who else solves this problem, and why do customers choose you over them?',
+  ),
+  page('Team and roles', 'team-and-roles', 'Who does what, and who owns which relationships or decisions?'),
+  page('Tools and stack', 'tools-and-stack', 'The systems your team and agents should know about.'),
+  page(
+    'Agent FAQ',
+    'agent-faq',
+    'Standing rules for agents: what they may promise, what they must escalate, and what never to invent.',
+  ),
+]
+
+const AGENCY_PAGES: readonly StarterHandbookPage[] = [
+  page('About us', 'about-us', 'What does your agency do, and what makes your team distinctive?'),
+  page(
+    'Services & capabilities',
+    'product',
+    'What services do you offer, and what kinds of clients or projects fit best?',
+  ),
+  page(
+    'Ideal client profile',
+    'ideal-customer-profile',
+    'Who is your best-fit client? Size, sector, budget, and the problems you solve best.',
+  ),
+  page('Voice and tone', 'voice-and-tone', 'How should Kelpie and your agents sound in client-facing writing?'),
+  page(
+    'Pricing & engagement models',
+    'pricing',
+    'How you price work: retainers, fixed bids, day rates, and typical scopes.',
+  ),
+  page('How we win work', 'how-we-sell', 'How you find and close clients: referrals, pitches, RFPs, and follow-up.'),
+  page(
+    'Competitive landscape',
+    'competitive-landscape',
+    'Who you compete with, and why clients choose you over alternatives.',
+  ),
+  page(
+    'Case studies & proof points',
+    'case-studies',
+    'Outcomes you can cite: client wins, metrics, and stories agents may reference.',
+  ),
+  page(
+    'How we deliver work',
+    'delivery-process',
+    'How a project runs from kickoff to handoff: phases, checkpoints, and client touchpoints.',
+  ),
+  page('Team and roles', 'team-and-roles', 'Who leads delivery, sales, and client relationships?'),
+  page('Tools and stack', 'tools-and-stack', 'The systems your team and agents should know about.'),
+  page(
+    'Agent FAQ',
+    'agent-faq',
+    'Standing rules for agents: what they may promise, what they must escalate, and what never to invent.',
+  ),
+]
+
+const NONPROFIT_PAGES: readonly StarterHandbookPage[] = [
+  page('About us & mission', 'about-us', 'Your mission, vision, and the change you exist to make.'),
+  page(
+    'Programs & impact',
+    'product',
+    'What programs or services you run, and what outcomes they aim for.',
+  ),
+  page(
+    'Who we serve',
+    'ideal-customer-profile',
+    'The communities, beneficiaries, or stakeholders your programs exist for.',
+  ),
+  page('Voice and tone', 'voice-and-tone', 'How should Kelpie and your agents sound when they write on your behalf?'),
+  page(
+    'How we engage supporters',
+    'how-we-sell',
+    'How you build relationships with donors, volunteers, partners, and the public.',
+  ),
+  page(
+    'Funding & donations',
+    'funding-and-donations',
+    'Revenue streams: donations, grants, memberships, and major-gift approaches.',
+  ),
+  page('Impact & outcomes', 'impact-metrics', 'How you measure success: outputs, outcomes, and stories you can cite.'),
+  page(
+    'Grant applications',
+    'grant-applications',
+    'How you find, qualify, and apply for grants; common requirements and deadlines.',
+  ),
+  page('Team and roles', 'team-and-roles', 'Who does what, and who owns programs, fundraising, and comms?'),
+  page('Tools and stack', 'tools-and-stack', 'The systems your team and agents should know about.'),
+  page(
+    'Agent FAQ',
+    'agent-faq',
+    'Standing rules for agents: what they may promise, what they must escalate, and what never to invent.',
+  ),
+]
+
+const COMMUNITY_PAGES: readonly StarterHandbookPage[] = [
+  page('About us', 'about-us', 'What your organisation is, its purpose, and who it serves.'),
+  page('What we offer', 'product', 'What members get: benefits, services, events, and community value.'),
+  page(
+    'Ideal member profile',
+    'ideal-customer-profile',
+    'Who should join, and what makes someone a good fit for your community?',
+  ),
+  page('Voice and tone', 'voice-and-tone', 'How should Kelpie and your agents sound when they write on your behalf?'),
+  page('Membership & fees', 'pricing', 'Membership tiers, fees, and what each level includes.'),
+  page(
+    'How we grow membership',
+    'how-we-sell',
+    'How you attract and retain members: outreach, events, referrals, and renewals.',
+  ),
+  page('Membership benefits', 'membership-benefits', 'What members receive: access, discounts, resources, and perks.'),
+  page(
+    'Events & programming',
+    'events-and-programming',
+    'Regular events, programs, and how members can participate.',
+  ),
+  page('Team and roles', 'team-and-roles', 'Who runs the organisation, and who owns membership and events?'),
+  page('Tools and stack', 'tools-and-stack', 'The systems your team and agents should know about.'),
+  page(
+    'Agent FAQ',
+    'agent-faq',
+    'Standing rules for agents: what they may promise, what they must escalate, and what never to invent.',
+  ),
 ]
 
-export function starterHandbookBody(title: string): string {
-  return `# ${title}\n\nWrite this page.`
+const PROFESSIONAL_SERVICES_PAGES: readonly StarterHandbookPage[] = [
+  page('About the practice', 'about-us', 'What your practice does, its history, and what distinguishes it.'),
+  page('Practice areas', 'product', 'The services and matters you handle, and what you do not take on.'),
+  page(
+    'Ideal client profile',
+    'ideal-customer-profile',
+    'Who your best-fit clients are: size, sector, matter types, and engagement style.',
+  ),
+  page('Voice and tone', 'voice-and-tone', 'How should Kelpie and your agents sound in client-facing writing?'),
+  page('Fee structures', 'pricing', 'How you charge: hourly, fixed, value-based, and typical ranges.'),
+  page(
+    'Business development',
+    'how-we-sell',
+    'How you win clients: referrals, networking, pitches, and follow-up.',
+  ),
+  page('Market position', 'competitive-landscape', 'How you compare to peer firms and why clients choose you.'),
+  page(
+    'Conflicts & ethics',
+    'conflicts-and-ethics',
+    'Conflict checks, ethical boundaries, and what agents must never assume or promise.',
+  ),
+  page('Team and roles', 'team-and-roles', 'Partners, associates, and who owns client relationships.'),
+  page('Tools and stack', 'tools-and-stack', 'The systems your team and agents should know about.'),
+  page(
+    'Agent FAQ',
+    'agent-faq',
+    'Standing rules for agents: what they may promise, what they must escalate, and what never to invent.',
+  ),
+]
+
+const CREATOR_PAGES: readonly StarterHandbookPage[] = [
+  page('About me', 'about-us', 'Who you are, what you create, and what your brand stands for.'),
+  page('What I create', 'product', 'Your content, products, or services, and what makes them distinctive.'),
+  page(
+    'Audience profile',
+    'ideal-customer-profile',
+    'Who follows you, who buys from you, and what they care about.',
+  ),
+  page('Voice and tone', 'voice-and-tone', 'How you sound across content, email, and brand partnerships.'),
+  page('Rates & packages', 'pricing', 'What you charge: sponsorship rates, consulting packages, and deliverables.'),
+  page(
+    'How I work with clients',
+    'how-we-sell',
+    'How inbound leads become paid work: discovery, scope, contracts, and delivery.',
+  ),
+  page(
+    'Brand partnerships & sponsorships',
+    'brand-partnerships',
+    'What you offer sponsors, your rates, and brands you will or will not work with.',
+  ),
+  page('Tools and stack', 'tools-and-stack', 'The systems you and your agents should know about.'),
+  page(
+    'Agent FAQ',
+    'agent-faq',
+    'Standing rules for agents: what they may promise, what they must escalate, and what never to invent.',
+  ),
+]
+
+export const HANDBOOK_TEMPLATES: Readonly<Record<HandbookTemplateId, HandbookTemplate>> = {
+  startup: {
+    id: 'startup',
+    label: 'Startup',
+    description: 'Product company, SaaS, or tech startup selling software or services.',
+    pages: STARTUP_PAGES,
+  },
+  agency: {
+    id: 'agency',
+    label: 'Agency',
+    description: 'Consultancy, design shop, dev shop, or marketing agency.',
+    pages: AGENCY_PAGES,
+  },
+  nonprofit: {
+    id: 'nonprofit',
+    label: 'Nonprofit',
+    description: 'Charity, foundation, or social enterprise.',
+    pages: NONPROFIT_PAGES,
+  },
+  community: {
+    id: 'community',
+    label: 'Community',
+    description: 'Club, association, co-op, or membership organisation.',
+    pages: COMMUNITY_PAGES,
+  },
+  'professional-services': {
+    id: 'professional-services',
+    label: 'Professional services',
+    description: 'Law, accounting, architecture, or advisory practice.',
+    pages: PROFESSIONAL_SERVICES_PAGES,
+  },
+  creator: {
+    id: 'creator',
+    label: 'Creator',
+    description: 'Solo creator, freelancer, or personal brand.',
+    pages: CREATOR_PAGES,
+  },
+}
+
+/** Default startup template pages — same list `onboarding.md` names. */
+export const STARTER_HANDBOOK_PAGES: readonly StarterHandbookPage[] = STARTUP_PAGES
+
+export function isStarterHandbookBody(page: { readonly slug: string; readonly body: string }): boolean {
+  for (const template of Object.values(HANDBOOK_TEMPLATES)) {
+    for (const def of template.pages) {
+      if (def.slug === page.slug && starterHandbookBody(def) === page.body) {
+        return true
+      }
+    }
+  }
+
+  return false
+}
+
+export function getHandbookPagesForTemplate(templateId: HandbookTemplateId): readonly StarterHandbookPage[] {
+  return HANDBOOK_TEMPLATES[templateId].pages
+}
+
+export function starterHandbookBody(page: StarterHandbookPage): string {
+  return `# ${page.title}\n\n${page.bodyPrompt}`
 }
 
 export interface StarterStage {

package/src/modules/workspace/workspaceAccessMiddleware.ts

@@ -23,10 +23,9 @@ import { WORKSPACE_ACCESS } from './capabilities.ts'
  *
  * Exempts `/v1/auth/*` and `/v1/account*`: they manage the *account*, not
  * the workspace, and a member of a workspace this gate has locked out
- * still needs to sign in, sign out, and see their own account to have any
- * chance of understanding why. There is no `/v1` endpoint to switch a
- * session to a different workspace membership — a session is bound to one
- * at login — so there is nothing further to exempt for that case.
+ * still needs to sign in, sign out, see their own account, list the
+ * workspaces they belong to (`GET /v1/auth/workspaces`), and switch this
+ * session to a different membership (`POST /v1/auth/workspace`).
  *
  * Also exempts `DELETE /v1/workspaces/:id` itself, and only that exact
  * path: a suspension must never trap an owner into a workspace they can no

package/src/runtime/events.ts

@@ -35,6 +35,8 @@ export const RECORD_OBJECT_TYPES = [
   'raise',
   'role',
   'candidate',
+  'event',
+  'attendance',
   'handbook_page',
   'form',
 ] as const

package/src/runtime/module.ts

@@ -1,4 +1,4 @@
-import type { Handler, Hono, MiddlewareHandler } from 'hono'
+import type { Context, Handler, Hono, MiddlewareHandler } from 'hono'
 import type { ZodType } from 'zod'
 
 import type { Actor } from '../lib/actor.ts'
@@ -58,6 +58,53 @@ export interface McpToolRegistry {
   tool<Input>(definition: McpToolDefinition<Input>): void
 }
 
+/**
+ * An identity a module verified somewhere else, handed back for core to sign in.
+ *
+ * Core never learns what OIDC or SAML is. Verification is the module's job and
+ * core does not redo it; core's job is that everything downstream of the cookie
+ * is identical to a password sign-in.
+ */
+export interface VerifiedIdentity {
+  readonly email: string
+  /** Core refuses the identity when false, rather than assuming the module checked. */
+  readonly emailVerified: boolean
+  /** The provider's display name, when it has one. The local part of the address is used otherwise. */
+  readonly name: string | null
+  /** Who verified it, recorded on the session: the module id, optionally suffixed (`sign-in:google`). */
+  readonly verifiedBy: string
+  /**
+   * What to do with an address core has never seen. The policy is the module's,
+   * because only it knows whether its provider vouches for strangers; executing
+   * it is core's.
+   */
+  readonly provision: 'create' | 'refuse'
+}
+
+/** The account a completed sign-in belongs to. */
+export interface CompletedSignInAccount {
+  readonly id: string
+  readonly email: string
+  readonly name: string
+  readonly emailVerified: boolean
+}
+
+export interface CompletedSignIn {
+  readonly account: CompletedSignInAccount
+  /** True when this sign-in provisioned the account rather than finding it. */
+  readonly created: boolean
+  readonly activeWorkspaceId: string | null
+}
+
+/**
+ * Completes a sign-in. Takes the Hono context because writing the session
+ * cookie on it is the point.
+ */
+export type ExternalSignInHandler = (
+  context: Context,
+  identity: VerifiedIdentity,
+) => Promise<CompletedSignIn>
+
 /**
  * What a module gets to build with, beyond its own contributions.
  *
@@ -86,6 +133,14 @@ export interface ModuleServices {
    * `secretEncryption`. Same fallback pattern as `appBaseUrl`.
    */
   readonly secretEncryption?: SecretEncryptionConfig | undefined
+  /**
+   * Whether the instance accepts a brand-new account, from `kelpie.config.ts`'s
+   * `signups` (or `SIGNUPS`). Undefined defaults to `true` (open), the same
+   * default `loadConfig` and `resolveKelpieConfig` use, so a caller that has
+   * not thought about it — a test, an older assembly — sees no change in
+   * behaviour.
+   */
+  readonly signupsEnabled?: boolean
 }
 
 export interface ModuleContext extends ModuleServices {
@@ -119,6 +174,28 @@ export interface ModuleContext extends ModuleServices {
    * delegates to the provider `email.provider` picked.
    */
   readonly email: EmailSender
+  /**
+   * Installs the one implementation of external sign-in. Core's `auth` module
+   * calls this; a second caller fails boot.
+   *
+   * The same shape as `provideEmailSender`: a capability only one module owns,
+   * reached by every module through a proxy, so registration order does not
+   * matter to a consumer.
+   */
+  provideExternalSignIn(handler: ExternalSignInHandler): void
+  /**
+   * Completes a sign-in for an identity this module already verified: finds or
+   * provisions the account, issues a session, and writes the session cookie on
+   * `context`.
+   *
+   * The alternative is a module writing core's `sessions` table itself, which
+   * ties it to core's token hashing, cookie flags and expiry with nothing
+   * keeping the two in step (`modules.md`).
+   *
+   * @throws ExternalSignInError when the identity is unverified, or unknown and
+   *   the module asked for `provision: 'refuse'`.
+   */
+  completeExternalSignIn(context: Context, identity: VerifiedIdentity): Promise<CompletedSignIn>
   /**
    * Registers routes that mount under `/v1/public`, take no credentials, and
    * answer cross-origin requests from any site.