question-bank-framework 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,106 @@
-# Temporary Holding Version
+# question-bank-framework
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Framework-style question bank (generalised from the COMP20008 bank). Downstream
+subjects bring their own `bank.config.ts` + `content/`; the framework ships the
+grid, filter DSL, quizzes, and Convex bindings as an npm package.
+
+Inspired by Vike's eject model: the stable core (`core/`) is never ejected;
+everything under `framework/` can be ejected into your repo and owned.
+
+## Use as a template
+
+```sh
+pnpm add question-bank-framework
+pnpm exec qb init                 # scaffolds bank.config.ts + content/ + src/routes/
+pnpm install
+pnpm dev
+```
+
+Your app owns:
+
+- `bank.config.ts` — `defineBank({ site, namespace, fields, questions, answers })`.
+  `fields: BankFieldDef[]` **is** your question schema: each field declares
+  `id/label/type/getValue/options/searchable/column`. Built-ins (`id/title/tags/status`) are automatic.
+- `content/questions.json`, `content/answers.ts`, `content/figures/`
+- Thin TanStack Start routes in `src/routes/` (see `template/src/routes/`)
+  wrapping `<BankProvider bank={bank}>` + `<AppShell brand>` + framework pages.
+
+## Reveal (eject) files
+
+```sh
+qb list                                  # ejectable files under framework/
+qb reveal framework/components/quiz-page.tsx
+qb reveal framework/components/quiz-page.tsx --to src/overrides --force
+```
+
+This copies the file into your repo (tracked in `.qb-manifest.json` with the
+framework version). Add an alias so the override shadows the package:
+
+```ts
+// vite.config.ts + tsconfig paths
+resolve: { alias: { 'question-bank-framework/framework': './src/overrides' } }
+```
+
+Eject is a last resort (same guidance as Vike): prefer `bank.config.ts`
+fields/columns/searchable flags first; eject when you need custom UI.
+
+## How Next.js / Vike do it (and what we copied)
+
+- **Next.js:** no eject command. Framework code stays hidden; you customize via
+  `next.config.js` + file conventions (`app/layout.tsx`, `error.tsx`,
+  `loading.tsx` override built-in fallbacks just by existing). Deep eject
+  (custom server/webpack fork) is possible but discouraged.
+- **Vike:** tiny stable core + thin extensions (`vike-react`…) using the same
+  public hooks as user code. Eject is first-class: remove the extension, copy
+  `node_modules/vike-xxx/` → `ejected/vike-xxx/` (manually or via the `eject`
+  package), then customize.
+
+We follow Vike: `core/` (types, `defineBank`, `BankProvider`, `useBank`) is the
+stable core; `framework/` (components/lib/routes/convex) is the ejectable
+extension layer; `qb reveal` is the copy command.
+
+## Layout
+
+- `core/` — never ejected: `types.ts` (`BaseQuestion`, `BankFieldDef`,
+  `defineBank`), `config.tsx` (`BankProvider`, `useBank`).
+- `framework/` — ejectable: `components/` (grid, quiz, filter builder,
+  shadcn `ui/`), `lib/` (generic filter DSL, namespaced quiz/status stores,
+  `convex-api.ts`), `convex/` (quizzes + questionStatuses tables).
+- `template/` — starter: `bank.config.ts` (COMP20008-like schema),
+  `content/` example, `src/routes/` thin wrappers.
+- `bin/qb.ts` (source; compiled to `bin/qb.js` with `pnpm build:bin`) — `list` / `reveal` / `init`.
+
+## Schema example
+
+```ts
+defineBank({
+  site: { title: '…', brand: 'fieldnotes' },
+  namespace: 'comp20008', // localStorage keys + Convex lookups
+  fields: [
+    { id: 'year', label: 'Year', type: 'select', getValue: (q) => String(q['year'] ?? '') },
+    { id: 'marks', label: 'Marks', type: 'number', getValue: (q) => q['marks'] ?? null },
+  ],
+  questions, // BaseQuestion[]: { id, title, prompt, tags, ...custom }
+  answers,   // Record<id, markdown>
+});
+```
+
+## Dev
+
+```sh
+pnpm install
+pnpm typecheck
+```
+
+## Release (npm + changesets)
+
+```sh
+pnpm changeset        # describe your change as patch/minor/major, then push
+```
+
+Pushing to `main` runs the release workflow: it opens a "Version Packages"
+PR (bump + CHANGELOG). Merge that PR and the workflow publishes to npm with
+OIDC trusted publishing and provenance attestations — no npm token needed.
+
+One-time setup: on npmjs.com, add this repo as a trusted publisher for the
+`question-bank-framework` package (no tokens or secrets to manage).

package/bin/qb.js

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+// `qb` — Vike-style eject CLI for question-bank-framework.
+//   qb list                        list ejectable framework files
+//   qb reveal <path> [--to <dir>]  copy framework/<path> into your repo to own it
+//   qb init [--to <dir>]           scaffold bank.config.ts + content/ + routes
+//
+// Eject model (like Vike's `eject` package): framework code ships in
+// node_modules/question-bank-framework/framework/. By default you import it.
+// `qb reveal` copies a file into your project (default: src/overrides/<path>)
+// where your Vite/TS alias shadows the package. Edit freely afterwards.
+//
+// NOTE: the installed bin is plain JS compiled from this file
+// (`pnpm build:bin`) — Node refuses to type-strip files under node_modules,
+// so bin/qb.js must stay committed alongside this source.
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const here = dirname(fileURLToPath(import.meta.url));
+const pkgRoot = resolve(here, '..');
+const frameworkDir = join(pkgRoot, 'framework');
+const templateDir = join(pkgRoot, 'template');
+const args = process.argv.slice(2);
+const cmd = args[0];
+function walk(dir, base = '') {
+    const out = [];
+    for (const entry of readdirSync(dir)) {
+        const full = join(dir, entry);
+        const rel = base ? `${base}/${entry}` : entry;
+        if (statSync(full).isDirectory())
+            out.push(...walk(full, rel));
+        else
+            out.push(rel);
+    }
+    return out.sort();
+}
+function pkgVersion() {
+    try {
+        const pkg = JSON.parse(readFileSync(join(pkgRoot, 'package.json'), 'utf8'));
+        return typeof pkg.version === 'string' ? pkg.version : '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+function readManifest(cwd) {
+    const path = join(cwd, '.qb-manifest.json');
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        if (parsed && typeof parsed.reveals === 'object' && parsed.reveals !== null) {
+            return { reveals: parsed.reveals };
+        }
+        return { reveals: {} };
+    }
+    catch {
+        return { reveals: {} };
+    }
+}
+function writeManifest(cwd, manifest) {
+    writeFileSync(join(cwd, '.qb-manifest.json'), JSON.stringify(manifest, null, 2) + '\n');
+}
+if (cmd === 'list' || !cmd) {
+    if (!existsSync(frameworkDir)) {
+        console.error(`framework/ not found at ${frameworkDir}`);
+        process.exit(1);
+    }
+    for (const f of walk(frameworkDir))
+        console.log(`framework/${f}`);
+    if (!cmd) {
+        console.log('\nUsage: qb reveal <framework/<path>> [--to <dir>] [--force]');
+    }
+}
+else if (cmd === 'reveal') {
+    const src = args[1];
+    if (!src) {
+        console.error('Usage: qb reveal <framework/<path>> [--to <dir>] [--force]');
+        process.exit(1);
+    }
+    const toIdx = args.indexOf('--to');
+    const force = args.includes('--force');
+    const destRoot = toIdx !== -1 && args[toIdx + 1] ? args[toIdx + 1] : 'src/overrides';
+    const rel = src.replace(/^framework\//, '');
+    const absSrc = join(frameworkDir, rel);
+    if (!existsSync(absSrc) || !statSync(absSrc).isFile()) {
+        console.error(`Not ejectable: ${src}\nRun \`qb list\` to see ejectable files.`);
+        process.exit(1);
+    }
+    const cwd = process.cwd();
+    const dest = resolve(cwd, destRoot, rel);
+    if (existsSync(dest) && !force) {
+        console.error(`Refusing to overwrite ${dest} (pass --force).`);
+        process.exit(1);
+    }
+    mkdirSync(dirname(dest), { recursive: true });
+    cpSync(absSrc, dest);
+    const manifest = readManifest(cwd);
+    manifest.reveals[`${destRoot}/${rel}`] = { src: `framework/${rel}`, version: pkgVersion(), revealedAt: new Date().toISOString() };
+    writeManifest(cwd, manifest);
+    console.log(`Revealed ${`framework/${rel}`} -> ${dest}`);
+    console.log('Add an alias so the override shadows the package, e.g. Vite resolve.alias + tsconfig paths:');
+    console.log(`  "${destRoot}/*" takes precedence over "question-bank-framework/framework/*"`);
+}
+else if (cmd === 'init') {
+    const toIdx = args.indexOf('--to');
+    const destRoot = toIdx !== -1 && args[toIdx + 1] ? args[toIdx + 1] : '.';
+    const cwd = resolve(process.cwd(), destRoot);
+    for (const f of walk(templateDir)) {
+        const from = join(templateDir, f);
+        const to = join(cwd, f);
+        mkdirSync(dirname(to), { recursive: true });
+        if (!existsSync(to))
+            cpSync(from, to);
+    }
+    console.log(`Scaffolded template into ${cwd}`);
+    console.log('Next: pnpm install, then point your routes at bank.config.ts (see template/src/routes/).');
+}
+else {
+    console.error(`Unknown command: ${cmd}\nCommands: list, reveal, init`);
+    process.exit(1);
+}

package/bin/qb.ts

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+// `qb` — Vike-style eject CLI for question-bank-framework.
+//   qb list                        list ejectable framework files
+//   qb reveal <path> [--to <dir>]  copy framework/<path> into your repo to own it
+//   qb init [--to <dir>]           scaffold bank.config.ts + content/ + routes
+//
+// Eject model (like Vike's `eject` package): framework code ships in
+// node_modules/question-bank-framework/framework/. By default you import it.
+// `qb reveal` copies a file into your project (default: src/overrides/<path>)
+// where your Vite/TS alias shadows the package. Edit freely afterwards.
+//
+// NOTE: the installed bin is plain JS compiled from this file
+// (`pnpm build:bin`) — Node refuses to type-strip files under node_modules,
+// so bin/qb.js must stay committed alongside this source.
+
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here: string = dirname(fileURLToPath(import.meta.url));
+const pkgRoot: string = resolve(here, '..');
+const frameworkDir: string = join(pkgRoot, 'framework');
+const templateDir: string = join(pkgRoot, 'template');
+
+const args: string[] = process.argv.slice(2);
+const cmd: string | undefined = args[0];
+
+function walk(dir: string, base = ''): string[] {
+  const out: string[] = [];
+  for (const entry of readdirSync(dir)) {
+    const full: string = join(dir, entry);
+    const rel: string = base ? `${base}/${entry}` : entry;
+    if (statSync(full).isDirectory()) out.push(...walk(full, rel));
+    else out.push(rel);
+  }
+  return out.sort();
+}
+
+function pkgVersion(): string {
+  try {
+    const pkg = JSON.parse(readFileSync(join(pkgRoot, 'package.json'), 'utf8')) as { version?: unknown };
+    return typeof pkg.version === 'string' ? pkg.version : '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+}
+
+interface RevealEntry {
+  src: string;
+  version: string;
+  revealedAt: string;
+}
+
+interface QbManifest {
+  reveals: Record<string, RevealEntry>;
+}
+
+function readManifest(cwd: string): QbManifest {
+  const path = join(cwd, '.qb-manifest.json');
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8')) as Partial<QbManifest>;
+    if (parsed && typeof parsed.reveals === 'object' && parsed.reveals !== null) {
+      return { reveals: parsed.reveals };
+    }
+    return { reveals: {} };
+  } catch {
+    return { reveals: {} };
+  }
+}
+
+function writeManifest(cwd: string, manifest: QbManifest): void {
+  writeFileSync(join(cwd, '.qb-manifest.json'), JSON.stringify(manifest, null, 2) + '\n');
+}
+
+if (cmd === 'list' || !cmd) {
+  if (!existsSync(frameworkDir)) {
+    console.error(`framework/ not found at ${frameworkDir}`);
+    process.exit(1);
+  }
+  for (const f of walk(frameworkDir)) console.log(`framework/${f}`);
+  if (!cmd) {
+    console.log('\nUsage: qb reveal <framework/<path>> [--to <dir>] [--force]');
+  }
+} else if (cmd === 'reveal') {
+  const src: string | undefined = args[1];
+  if (!src) {
+    console.error('Usage: qb reveal <framework/<path>> [--to <dir>] [--force]');
+    process.exit(1);
+  }
+  const toIdx: number = args.indexOf('--to');
+  const force: boolean = args.includes('--force');
+  const destRoot: string = toIdx !== -1 && args[toIdx + 1] ? args[toIdx + 1] : 'src/overrides';
+  const rel: string = src.replace(/^framework\//, '');
+  const absSrc: string = join(frameworkDir, rel);
+  if (!existsSync(absSrc) || !statSync(absSrc).isFile()) {
+    console.error(`Not ejectable: ${src}\nRun \`qb list\` to see ejectable files.`);
+    process.exit(1);
+  }
+  const cwd: string = process.cwd();
+  const dest: string = resolve(cwd, destRoot, rel);
+  if (existsSync(dest) && !force) {
+    console.error(`Refusing to overwrite ${dest} (pass --force).`);
+    process.exit(1);
+  }
+  mkdirSync(dirname(dest), { recursive: true });
+  cpSync(absSrc, dest);
+  const manifest: QbManifest = readManifest(cwd);
+  manifest.reveals[`${destRoot}/${rel}`] = { src: `framework/${rel}`, version: pkgVersion(), revealedAt: new Date().toISOString() };
+  writeManifest(cwd, manifest);
+  console.log(`Revealed ${`framework/${rel}`} -> ${dest}`);
+  console.log('Add an alias so the override shadows the package, e.g. Vite resolve.alias + tsconfig paths:');
+  console.log(`  "${destRoot}/*" takes precedence over "question-bank-framework/framework/*"`);
+} else if (cmd === 'init') {
+  const toIdx: number = args.indexOf('--to');
+  const destRoot: string = toIdx !== -1 && args[toIdx + 1] ? args[toIdx + 1] : '.';
+  const cwd: string = resolve(process.cwd(), destRoot);
+  for (const f of walk(templateDir)) {
+    const from: string = join(templateDir, f);
+    const to: string = join(cwd, f);
+    mkdirSync(dirname(to), { recursive: true });
+    if (!existsSync(to)) cpSync(from, to);
+  }
+  console.log(`Scaffolded template into ${cwd}`);
+  console.log('Next: pnpm install, then point your routes at bank.config.ts (see template/src/routes/).');
+} else {
+  console.error(`Unknown command: ${cmd}\nCommands: list, reveal, init`);
+  process.exit(1);
+}

package/core/config.tsx

@@ -0,0 +1,52 @@
+// Bank runtime context. Framework components consume the active bank via
+// `useBank()` instead of importing `@/data/questions` directly, so a
+// downstream subject only owns `bank.config.ts` + `content/`.
+
+import { createContext, useContext, type ReactNode } from 'react';
+import type { Bank } from './types.ts';
+
+export const BankContext = createContext<Bank | null>(null);
+
+export function BankProvider({ bank, children }: { bank: Bank; children: ReactNode }) {
+  return <BankContext.Provider value={bank}>{children}</BankContext.Provider>;
+}
+
+export function useBank(): Bank {
+  const bank = useContext(BankContext);
+  if (!bank) {
+    throw new Error(
+      'useBank() called outside <BankProvider>. Wrap your routes with <BankProvider bank={bank}>.',
+    );
+  }
+  return bank;
+}
+
+export { defineBank } from './types.ts';
+export type {
+  Bank,
+  BankFieldDef,
+  BankFieldOption,
+  BankFieldType,
+  BankFilterOperatorId,
+  BankSiteConfig,
+  BaseQuestion,
+  DefineBankInput,
+  QuestionKind,
+  QuestionOption,
+  QuestionStatus,
+  QuestionStatusMap,
+  QuizAnswer,
+  QuizSession,
+} from './types.ts';
+export {
+  getCorrectIds,
+  isAnswerCorrect,
+  isAnswerProvided,
+  isChoiceQuestion,
+  questionKind,
+  questionKindLabels,
+  questionKinds,
+  scoreAnswers,
+  toSelectedIds,
+} from './types.ts';
+export { questionStatuses } from './types.ts';

package/core/index.ts

@@ -0,0 +1,35 @@
+// Re-export the stable core: types + BankContext/useBank/defineBank.
+// Framework code (ejectable) lives under framework/.
+
+export {
+  BankContext,
+  BankProvider,
+  useBank,
+  defineBank,
+  getCorrectIds,
+  isAnswerCorrect,
+  isAnswerProvided,
+  isChoiceQuestion,
+  questionKind,
+  questionKindLabels,
+  questionKinds,
+  questionStatuses,
+  scoreAnswers,
+  toSelectedIds,
+} from './config.tsx';
+export type {
+  Bank,
+  BankFieldDef,
+  BankFieldOption,
+  BankFieldType,
+  BankFilterOperatorId,
+  BankSiteConfig,
+  BaseQuestion,
+  DefineBankInput,
+  QuestionKind,
+  QuestionOption,
+  QuestionStatus,
+  QuestionStatusMap,
+  QuizAnswer,
+  QuizSession,
+} from './config.tsx';