@biffo/cli 0.314.2 → 0.315.0

package/_skeletons/plugin-template/web/src/App.test.tsx

@@ -0,0 +1,17 @@
+import { render, screen } from '@testing-library/react'
+import { describe, expect, it } from 'vitest'
+
+import App from './App'
+
+describe('App', () => {
+  it('renders text naming the plugin', () => {
+    render(<App />)
+
+    // A blank shell that merely mounts proves nothing — this asserts the
+    // actual plugin name is on the page. `biffo plugin create` rewrites
+    // `example-plugin` to the real slug everywhere (see
+    // ../.scaffold-tokens.json two directories up), including this literal,
+    // so the assertion stays true for whatever plugin gets scaffolded.
+    expect(screen.getByRole('heading', { name: 'example-plugin' })).toBeInTheDocument()
+  })
+})

package/_skeletons/plugin-template/web/src/App.tsx

@@ -0,0 +1,23 @@
+/**
+ * Starter founder-facing surface (`user_frontend`, ADR-0021 §2). Served
+ * UNAUTHENTICATED by the shared plugin host at
+ * `/api/v1/plugins/example-plugin/ui/` — unlike web-admin's `App`, there is no
+ * session to read here: `required_group` on the manifest's `user_frontend`
+ * block does not gate this shell (see docs/guides/plugins.md), so this screen
+ * must not assume a signed-in caller.
+ *
+ * It exists to prove the `user_frontend` bundle actually builds and renders
+ * something that names the plugin — not to be a feature. Replace it with this
+ * plugin's own founder-facing UI.
+ */
+export default function App() {
+  return (
+    <main className="page">
+      <h1>example-plugin</h1>
+      <p className="muted">
+        This is the founder-facing starter screen for the example-plugin plugin. Replace it with
+        this plugin&apos;s own UI.
+      </p>
+    </main>
+  )
+}

package/_skeletons/plugin-template/web/src/base-path.test.ts

@@ -0,0 +1,70 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { describe, expect, it } from 'vitest'
+
+/**
+ * The Vite `base` must name THIS plugin, and the built HTML's asset
+ * references must actually live under it.
+ *
+ * Ported from web-admin/src/base-path.test.ts, itself ported from
+ * idea-scout's guard (biffo-template#1492): a vite.config.ts pasted from a
+ * sibling and left pointing at the sibling's base — 503, blank page, and
+ * every other local gate (eslint, tsc, unit tests, `vite build` itself)
+ * passed, because `base` only affects the URLs inside the emitted HTML. This
+ * copy exists because `user_frontend` (`/ui/`) is a separate mount from
+ * `admin_ingress` (`/admin/`) with its own base string to get wrong.
+ *
+ * The expected plugin name comes from `biffo.plugin.json`'s own `name`
+ * field — an independent ground truth scaffolded alongside vite.config.ts —
+ * NOT from parsing it back out of the config under test. An earlier version
+ * of this file did the latter and was proven tautological
+ * (biffo-template#2024): it regex-extracted the "expected" name from the same
+ * base string it then checked, so a base that was internally self-consistent
+ * but named the WRONG plugin — exactly the idea-scout#1492
+ * paste-from-a-sibling shape — still passed every assertion. `biffo.plugin.json`'s
+ * `name` is set once, at scaffold time, by `biffo plugin create`'s token
+ * substitution — the same operation that rewrites vite.config.ts's own
+ * `example-plugin` token — so it cannot be derived from a wrong
+ * vite.config.ts and cannot be fooled by a bad paste from it.
+ */
+const ROOT = join(__dirname, '..')
+
+function expectedPluginName(): string {
+  const manifest = JSON.parse(readFileSync(join(ROOT, '..', 'biffo.plugin.json'), 'utf8')) as {
+    name?: string
+  }
+  expect(manifest.name, 'biffo.plugin.json has no top-level `name`').toBeTruthy()
+  return manifest.name!
+}
+
+describe('vite base path', () => {
+  const plugin = expectedPluginName()
+  const config = readFileSync(join(ROOT, 'vite.config.ts'), 'utf8')
+
+  it('is the full API Gateway path for THIS plugin', () => {
+    expect(config).toContain(`base: '/api/v1/plugins/${plugin}/ui/'`)
+  })
+
+  // Deliberately no "the config mentions no other plugin" test — see
+  // web-admin/src/base-path.test.ts's own comment on why that shape is wrong.
+
+  it('the built index.html requests assets under that base', () => {
+    // Skipped when dist/ is absent (a source checkout, not a built one). CI
+    // runs `build` before `test` — but if it ever does not, this must not
+    // pass silently, so the skip is explicit and visible.
+    let html: string
+    try {
+      html = readFileSync(join(ROOT, 'dist', 'index.html'), 'utf8')
+    } catch {
+      console.warn('dist/index.html absent — build not run; base-path check skipped')
+      return
+    }
+    const srcs = [...html.matchAll(/(?:src|href)="([^"]+)"/g)].map((m) => m[1])
+    const assetRefs = srcs.filter((s) => s.includes('/assets/'))
+    expect(assetRefs.length, 'no asset references in the built HTML').toBeGreaterThan(0)
+    for (const ref of assetRefs) {
+      expect(ref.startsWith(`/api/v1/plugins/${plugin}/ui/`), `bad asset path: ${ref}`).toBe(true)
+    }
+  })
+})

package/_skeletons/plugin-template/web/src/index.css

@@ -0,0 +1,33 @@
+/* Shares the design tokens the rest of the estate uses so a plugin's
+   founder-facing shell does not become its own brand blue (the drift
+   @biffo/design-tokens was created to end) — same reasoning as
+   web-admin/src/index.css. */
+@import '@biffo/design-tokens/tokens.css';
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  font-family: var(--font-sans, system-ui, sans-serif);
+  color: var(--text, #1b1c1f);
+  background: var(--bg, #f7f8fa);
+}
+
+.page {
+  max-width: 60rem;
+  margin: 0 auto;
+  padding: 2rem 1.5rem 4rem;
+}
+
+h1 {
+  font-size: 1.55rem;
+  margin: 0 0 0.35rem;
+}
+
+.muted {
+  color: var(--text-muted, #5b6070);
+  font-size: 0.9rem;
+  margin: 0 0 1.25rem;
+}

package/_skeletons/plugin-template/web/src/main.tsx

@@ -0,0 +1,11 @@
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+
+import App from './App'
+import './index.css'
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+)

package/_skeletons/plugin-template/web/src/test-setup.ts

@@ -0,0 +1 @@
+import '@testing-library/jest-dom'

package/_skeletons/plugin-template/web/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "useDefineForClassFields": true,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "types": ["vitest/globals", "@testing-library/jest-dom"]
+  },
+  "include": ["src", "vite.config.ts"]
+}

package/_skeletons/plugin-template/web/vite.config.ts

@@ -0,0 +1,26 @@
+import { defineConfig } from 'vitest/config'
+import react from '@vitejs/plugin-react'
+
+// Served by the shared plugin host at /api/v1/plugins/example-plugin/ui/*
+// (docs/guides/plugins.md's "User-facing frontend" section, ADR-0021 §2) —
+// UNAUTHENTICATED, unlike web-admin's sibling: a plain browser navigation can
+// never attach a bearer token, so this shell is served with no group_gate at
+// all (services/_plugin-host/src/plugin_host/mount.py). Every asset/link URL
+// must carry the full prefix, INCLUDING THIS PLUGIN'S OWN NAME. `biffo plugin
+// create` rewrites `example-plugin` to the real slug (see
+// .scaffold-tokens.json); do not hand-edit this after scaffolding without
+// updating BOTH this file and base-path.test.ts.
+//
+// Mirrors web-admin/vite.config.ts's own comment almost verbatim, because the
+// trap it describes is identical here: idea-scout's copy of THAT file was
+// pasted from ideation's and kept ideation's base, and no local gate caught
+// it — lint, typecheck, unit tests and the production build all passed,
+// because `base` only affects the URLs inside the emitted HTML. It was only
+// visible by loading the page and reading the network log. Hence the full
+// path, and hence base-path.test.ts asserting it stays correct.
+export default defineConfig({
+  base: '/api/v1/plugins/example-plugin/ui/',
+  plugins: [react()],
+  build: { outDir: 'dist' },
+  test: { environment: 'jsdom', globals: true, setupFiles: ['./src/test-setup.ts'] },
+})

package/_skeletons/plugin-template/web-admin/src/base-path.test.ts

@@ -16,21 +16,33 @@ import { describe, expect, it } from 'vitest'
  * check, generalised so a plugin scaffolded from this skeleton inherits it
  * automatically rather than every plugin author re-discovering the bug.
  *
- * Reads the plugin name OUT of vite.config.ts itself rather than hardcoding
- * it, so this file needs no token substitution at scaffold time and stays
- * correct whatever `biffo plugin create` rewrites `base` to.
+ * The expected plugin name comes from `biffo.plugin.json`'s own `name`
+ * field — an independent ground truth scaffolded alongside vite.config.ts —
+ * NOT from parsing it back out of the config under test. An earlier version
+ * of this file did the latter and was proven tautological
+ * (biffo-template#2024): it regex-extracted the "expected" name from the same
+ * base string it then checked, so a base that was internally self-consistent
+ * but named the WRONG plugin — exactly the idea-scout#1492
+ * paste-from-a-sibling shape this file is named after — still passed every
+ * assertion. `biffo.plugin.json`'s `name` is set once, at scaffold time, by
+ * `biffo plugin create`'s token substitution — the same operation that
+ * rewrites vite.config.ts's own `example-plugin` token — so it cannot be
+ * derived from a wrong vite.config.ts and cannot be fooled by a bad paste
+ * from it.
  */
 const ROOT = join(__dirname, '..')
 
-function pluginFromConfig(config: string): string {
-  const match = config.match(/base:\s*'\/api\/v1\/plugins\/([^/]+)\/admin\/'/)
-  expect(match, "no `base: '/api/v1/plugins/<name>/admin/'` found in vite.config.ts").not.toBeNull()
-  return match![1]
+function expectedPluginName(): string {
+  const manifest = JSON.parse(readFileSync(join(ROOT, '..', 'biffo.plugin.json'), 'utf8')) as {
+    name?: string
+  }
+  expect(manifest.name, 'biffo.plugin.json has no top-level `name`').toBeTruthy()
+  return manifest.name!
 }
 
 describe('vite base path', () => {
+  const plugin = expectedPluginName()
   const config = readFileSync(join(ROOT, 'vite.config.ts'), 'utf8')
-  const plugin = pluginFromConfig(config)
 
   it('is the full API Gateway path for THIS plugin', () => {
     expect(config).toContain(`base: '/api/v1/plugins/${plugin}/admin/'`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@biffo/cli",
-  "version": "0.314.2",
+  "version": "0.315.0",
   "description": "Biffo project scaffolding CLI",
   "license": "MIT",
   "type": "module",