@bevel-software/platform-core-backend 0.26.0 → 0.27.0

package/src/modules/onboarding/__tests__/starter-packs.test.ts

@@ -0,0 +1,169 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { DEFAULT_KB_LAYOUT } from '@bevel-software/platform-shared';
+import { defaultStarterPacksDir } from '../../../assets.js';
+import { NodeFs } from '../../kb-fs/node-fs.js';
+import { loadStarterPacks, packProblem, readStarterPack, starterPackFiles } from '../starter-packs.js';
+
+const disk = new NodeFs();
+
+/**
+ * Reading the packs: what makes a folder a pack, that one bad folder never
+ * takes the others away, and how a pack's files map onto a deployment's
+ * layout.
+ */
+
+let root = '';
+beforeEach(async () => {
+  root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-starter-packs-'));
+});
+afterEach(async () => {
+  await fs.rm(root, { recursive: true, force: true });
+});
+
+/** A pack.yaml with every field valid, then `over` on top. */
+function manifest(id: string, over: Record<string, string> = {}): string {
+  const fields: Record<string, string> = {
+    id,
+    name: id[0]!.toUpperCase() + id.slice(1),
+    description: `Pages for ${id}.`,
+    order: '5',
+    firstPagePrompt: `Write the ${id} page.`,
+    suggestedPages: '[About us, Glossary]',
+    ...over,
+  };
+  return Object.entries(fields)
+    .map(([k, v]) => `${k}: ${v}`)
+    .join('\n');
+}
+
+async function write(rel: string, content: string | Buffer): Promise<void> {
+  const abs = path.join(root, ...rel.split('/'));
+  await fs.mkdir(path.dirname(abs), { recursive: true });
+  await fs.writeFile(abs, content);
+}
+
+describe('loadStarterPacks', () => {
+  it('lists the valid packs in chip order, then by name', async () => {
+    // Sales and Engineering share an order, so the name decides between them.
+    await write('sales/pack.yaml', manifest('sales', { order: '1' }));
+    await write('engineering/pack.yaml', manifest('engineering', { order: '1' }));
+    await write('general/pack.yaml', manifest('general', { name: 'Something else', order: '99' }));
+    await write('README.md', '# not a pack\n');
+
+    const packs = await loadStarterPacks(disk,root);
+
+    expect(packs.map((p) => p.id)).toEqual(['engineering', 'sales', 'general']);
+    expect(packs[2]).toMatchObject({
+      name: 'Something else',
+      description: 'Pages for general.',
+      order: 99,
+      firstPagePrompt: 'Write the general page.',
+      suggestedPages: ['About us', 'Glossary'],
+      dir: path.join(root, 'general'),
+    });
+  });
+
+  it('skips a folder that is not a pack and keeps offering the rest', async () => {
+    await write('good/pack.yaml', manifest('good'));
+    await write('no-manifest/KnowledgeBase/Page.md', '# Page\n');
+    await write('broken-yaml/pack.yaml', 'id: [unclosed');
+    await write('wrong-id/pack.yaml', manifest('something-else'));
+    await write('no-order/pack.yaml', manifest('no-order', { order: 'soon' }));
+
+    expect((await loadStarterPacks(disk,root)).map((p) => p.id)).toEqual(['good']);
+  });
+
+  it('offers nothing when the folder is not there', async () => {
+    expect(await loadStarterPacks(disk,path.join(root, 'missing'))).toEqual([]);
+  });
+
+  it('the packaged packs all read as packs', async () => {
+    const dirs = (await fs.readdir(defaultStarterPacksDir(), { withFileTypes: true })).filter((e) => e.isDirectory());
+    const packs = await loadStarterPacks(disk,defaultStarterPacksDir());
+    expect(packs.map((p) => p.id).sort()).toEqual(dirs.map((d) => d.name).sort());
+  });
+
+  it("the packaged skills are named, described, unique across packs, and free of their upstream's install", async () => {
+    const names = new Map<string, string>();
+    for (const pack of await loadStarterPacks(disk,defaultStarterPacksDir())) {
+      for (const file of await starterPackFiles(disk, pack,DEFAULT_KB_LAYOUT)) {
+        if (path.posix.basename(file.repoPath) !== 'SKILL.md') continue;
+        const text = file.content as string;
+        const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text)?.[1] ?? '';
+        const name = /^name:\s*(.+)$/m.exec(frontmatter)?.[1]?.trim();
+        expect(name, `${pack.id}: ${file.repoPath} has no name`).toBeTruthy();
+        expect(frontmatter, `${pack.id}: ${file.repoPath} has no description`).toMatch(/^description:/m);
+        expect(path.posix.basename(path.posix.dirname(file.repoPath)), `${file.repoPath}: folder and name differ`).toBe(name);
+        expect(names.get(name!), `skill "${name}" is in two packs`).toBeUndefined();
+        names.set(name!, pack.id);
+        expect(text, `${file.repoPath} points into an upstream install`).not.toMatch(/~\/\.claude\/skills/);
+      }
+    }
+    expect(names.size).toBeGreaterThan(0);
+  });
+});
+
+describe('packProblem', () => {
+  const complete = { id: 'x', name: 'X', description: 'd', firstPagePrompt: 'p', order: 1, suggestedPages: ['A'] };
+
+  it.each([
+    ['not a mapping', ['a list'], 'x', 'mapping'],
+    ['an id that is not kebab-case', { ...complete, id: 'Sales' }, 'Sales', '`id`'],
+    ['an id that is not the folder', complete, 'y', "folder's name"],
+    ['the reserved skip', { ...complete, id: 'none' }, 'none', 'reserved'],
+    ['a missing name', { ...complete, name: undefined }, 'x', '`name`'],
+    ['a blank first-page prompt', { ...complete, firstPagePrompt: '  ' }, 'x', '`firstPagePrompt`'],
+    ['an order that is not a number', { ...complete, order: '1' }, 'x', '`order`'],
+    ['suggested pages that are not names', { ...complete, suggestedPages: [3] }, 'x', '`suggestedPages`'],
+  ])('refuses %s', (_label, value, folder, mentions) => {
+    expect(packProblem(value, folder)).toContain(mentions);
+  });
+
+  it('accepts a complete manifest', () => {
+    expect(packProblem(complete, 'x')).toBeNull();
+  });
+});
+
+describe('starterPackFiles', () => {
+  it('writes the pack under the layout in effect, rendered, and leaves everything else behind', async () => {
+    await write('eng/pack.yaml', manifest('eng'));
+    await write('eng/notes.md', 'for whoever maintains the pack\n');
+    await write('eng/KnowledgeBase/About us.md', '# About us\n\nSee {{pluginsDir}}/eng-starter.\n');
+    await write('eng/KnowledgeBase/.DS_Store', 'junk');
+    await write('eng/Plugins/eng-starter/skills/review/SKILL.md', '---\nname: review\n---\n');
+    await write('eng/Plugins/eng-starter/logo.png', Buffer.from([0x89, 0x50, 0x00, 0x01]));
+    await write('eng/Skills/Shared/tidy/SKILL.md', '---\nname: tidy\n---\n');
+    const pack = (await readStarterPack(disk, path.join(root, 'eng')))!;
+
+    const files = await starterPackFiles(disk, pack,{
+      ...DEFAULT_KB_LAYOUT,
+      knowledgeBaseDir: 'Wiki',
+      pluginsDir: 'Teams',
+      skillsDir: 'Playbooks',
+    });
+
+    expect(files.map((f) => [f.root, f.repoPath])).toEqual([
+      ['KnowledgeBase', 'Wiki/About us.md'],
+      ['Plugins', 'Teams/eng-starter/logo.png'],
+      ['Plugins', 'Teams/eng-starter/skills/review/SKILL.md'],
+      ['Skills', 'Playbooks/Shared/tidy/SKILL.md'],
+    ]);
+    // Text is rendered for the layout; a binary file is copied as it is.
+    expect(files[0]!.content).toBe('# About us\n\nSee Teams/eng-starter.\n');
+    expect(Buffer.isBuffer(files[1]!.content)).toBe(true);
+  });
+
+  it('treats a pack folder that is a file as empty, and still reads the rest of the pack', async () => {
+    await write('eng/pack.yaml', manifest('eng'));
+    await write('eng/KnowledgeBase/About us.md', '# About us\n');
+    await write('eng/Plugins', 'not a folder\n');
+    const pack = (await readStarterPack(disk, path.join(root, 'eng')))!;
+
+    const files = await starterPackFiles(disk, pack,DEFAULT_KB_LAYOUT);
+
+    expect(files.map((f) => f.repoPath)).toEqual(['KnowledgeBase/About us.md']);
+  });
+});

package/src/modules/onboarding/onboarding.contract.ts

@@ -0,0 +1,85 @@
+/**
+ * The starter-pack question as its callers see it: what the routes ask of
+ * the service, and the shapes they answer with. The frontend's
+ * `starter-packs.api.ts` MIRRORS the two answer types.
+ */
+
+import type { AuthUser } from '@bevel-software/platform-shared';
+import type { StarterPackSummary } from './starter-packs.js';
+
+/** `GET /api/onboarding/starter-packs`. */
+export interface StarterPacksAnswer {
+  /** Whether the caller should be asked: an admin, nothing chosen yet, a knowledge folder still new. */
+  offered: boolean;
+  /** The recorded answer — a pack's id, or `none` — or null while nobody has answered. */
+  chosen: string | null;
+  /** The packs to choose from, in chip order. Empty for a member, who is never asked. */
+  packs: StarterPackSummary[];
+  /** The chosen pack, for the first-page prompt — null when none was (or `none` was). */
+  chosenPack: ChosenStarterPack | null;
+}
+
+export interface ChosenStarterPack {
+  id: string;
+  name: string;
+  /** The team's own "write your first page" request. */
+  firstPagePrompt: string;
+  /**
+   * The pack's pages that still hold exactly what the pack wrote, as
+   * workspace-relative paths — those the caller may read, and no other:
+   * placeholders, not pages anyone wrote, so they do not tick "Write your
+   * first page".
+   */
+  starterPages: string[];
+}
+
+/** `POST /api/onboarding/starter-pack`. */
+export interface StarterPackApplied {
+  id: string;
+  /** The chosen pack's name; null for `none`. */
+  name: string | null;
+  /** Pages and skills the commit added — what was absent, not what the pack holds. */
+  pages: number;
+  skills: number;
+  /** What to tell the person: "Added 4 pages and 4 skills for Engineering." Empty for `none`. */
+  summary: string;
+}
+
+/** The workspaces the service reads and writes: the default branch's checkout, by its id. */
+export interface StarterPackWorkspaces {
+  getOrCreateForBranch(branch: string): Promise<{ id: string }>;
+  getWorkspacePath(workspaceId: string): Promise<string>;
+  hasBootstrappedWorkspace(workspaceId: string): Promise<boolean>;
+}
+
+/**
+ * The deployment settings the service keeps its answer and its claim in:
+ * `recordIfAbsent` takes the claim, `swapIfValue` takes over an expired one
+ * and releases one's own, `record` keeps the answer, `reload` reads what
+ * the database (every replica) holds.
+ */
+export interface StarterPackSettings {
+  reload(key: string): Promise<string>;
+  record(entries: Record<string, string>, updatedBy: string | null): Promise<void>;
+  recordIfAbsent(key: string, value: string, updatedBy: string | null): Promise<boolean>;
+  swapIfValue(key: string, expected: string, next: string | null, updatedBy: string | null): Promise<boolean>;
+}
+
+/** The plugin creation's identity lock, held over the name check and the commit of a pack's plugins. */
+export interface PluginIdentityLocks {
+  withIdentities<T>(names: string[], fn: () => Promise<T>): Promise<T>;
+}
+
+/**
+ * What the onboarding routes depend on. `status` answers anyone signed in;
+ * `choose` refuses a member (403), a question no longer asked (409) and a
+ * pack that does not exist (404) with a `WorkflowDomainError` carrying that
+ * status. One failure without a status is read by the route all the same:
+ * the batch write's "locked by …" refusal, which it answers as a 409 to
+ * try again, since nothing was committed. Any other failure is the
+ * route's generic 500.
+ */
+export interface IStarterPackService {
+  status(user: Pick<AuthUser, 'email'>): Promise<StarterPacksAnswer>;
+  choose(user: AuthUser, id: string): Promise<StarterPackApplied>;
+}

package/src/modules/onboarding/onboarding.routes.ts

@@ -0,0 +1,85 @@
+import express from 'express';
+import type { AuthUser } from '@bevel-software/platform-shared';
+import { logger } from '../../shared/logging.js';
+import { WorkflowDomainError } from '../../shared/domain-errors.js';
+import type { IStarterPackService } from './onboarding.contract.js';
+import '../auth/auth.middleware.js'; // Express Request augmentation (req.userId)
+
+const log = logger('starter-packs');
+
+/**
+ * The starter-pack question (see `starter-pack.service.ts`), JWT-only:
+ *
+ *   GET  /api/onboarding/starter-packs → `StarterPacksAnswer`
+ *   POST /api/onboarding/starter-pack  { id } → `StarterPackApplied`
+ *
+ * The GET answers anyone signed in — a member is never offered the question
+ * but follows the chosen pack's first-page prompt like everybody else — and
+ * is never cached: the answer changes the moment someone chooses. The POST is
+ * the admin's (403 otherwise; the service checks), 409 once the question is
+ * no longer asked, and `id: "none"` is "I'll start from scratch".
+ */
+export function createOnboardingRoutes(
+  starterPacks: IStarterPackService,
+  resolveUser: (req: express.Request) => Promise<AuthUser | null>,
+): express.Router {
+  const router = express.Router();
+
+  /**
+   * The caller, or null once the response is written: 401 for nobody signed
+   * in, and 500 when that could not be told — a database outage is not an
+   * expired session, and saying so sends people to sign in again for nothing.
+   */
+  async function caller(req: express.Request, res: express.Response): Promise<AuthUser | null> {
+    let user: AuthUser | null;
+    try {
+      user = await resolveUser(req);
+    } catch (err) {
+      log.error('could not resolve the caller:', { err });
+      res.status(500).json({ error: 'Could not tell who is signed in. Try again.' });
+      return null;
+    }
+    if (!user) res.status(401).json({ error: 'Unauthenticated' });
+    return user;
+  }
+
+  router.get('/onboarding/starter-packs', async (req, res) => {
+    res.set('Cache-Control', 'no-store');
+    const user = await caller(req, res);
+    if (!user) return;
+    try {
+      res.json(await starterPacks.status(user));
+    } catch (err) {
+      log.error('starter packs status failed:', { err });
+      res.status(500).json({ error: 'Could not load the starter packs' });
+    }
+  });
+
+  router.post('/onboarding/starter-pack', express.json(), async (req, res) => {
+    const user = await caller(req, res);
+    if (!user) return;
+    const id = (req.body as { id?: unknown } | undefined)?.id;
+    if (typeof id !== 'string' || !id.trim()) {
+      res.status(400).json({ error: 'Say which starter pack: `id`, or "none" to skip.' });
+      return;
+    }
+    try {
+      res.json(await starterPacks.choose(user, id.trim()));
+    } catch (err) {
+      if (err instanceof WorkflowDomainError) {
+        res.status(err.status).json({ error: err.message });
+        return;
+      }
+      // The batch write's status-less refusal: one of the pack's paths is
+      // being written by someone else right now. Nothing was committed.
+      if (err instanceof Error && /locked by /.test(err.message)) {
+        res.status(409).json({ error: 'Someone is editing the knowledge base right now. Try again in a moment.' });
+        return;
+      }
+      log.error('adding a starter pack failed:', { err });
+      res.status(500).json({ error: 'Could not add the starter pages. Nothing was changed.' });
+    }
+  });
+
+  return router;
+}