question-bank-framework 0.0.0-stage → 0.1.1

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,38 @@
+// 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,
+  QuestionStatus,
+  QuestionStatusMap,
+  QuizSession,
+} from './types.ts';
+export { questionStatuses } from './types.ts';

package/core/index.ts

@@ -0,0 +1,17 @@
+// Re-export the stable core: types + BankContext/useBank/defineBank.
+// Framework code (ejectable) lives under framework/.
+
+export { BankContext, BankProvider, useBank, defineBank, questionStatuses } from './config.tsx';
+export type {
+  Bank,
+  BankFieldDef,
+  BankFieldOption,
+  BankFieldType,
+  BankFilterOperatorId,
+  BankSiteConfig,
+  BaseQuestion,
+  DefineBankInput,
+  QuestionStatus,
+  QuestionStatusMap,
+  QuizSession,
+} from './config.tsx';

package/core/types.ts

@@ -0,0 +1,111 @@
+// Core question + bank types. Framework-owned, never ejected.
+// A bank's question shape is config-defined: every question has the four
+// core fields, plus arbitrary subject-specific metadata (year, marks, …).
+
+export const questionStatuses = ['unanswered', 'revisit', 'complete'] as const;
+
+export type QuestionStatus = (typeof questionStatuses)[number];
+export type QuestionStatusMap = Record<string, QuestionStatus>;
+
+export interface BaseQuestion {
+  id: string;
+  title: string;
+  prompt: string;
+  tags: string[];
+  // Subject-specific fields (e.g. year, semester, marks, source).
+  [key: string]: unknown;
+}
+
+export interface QuizSession {
+  id: string;
+  title: string;
+  questionIds: string[];
+  answers: Record<string, string>;
+  currentQuestion: number;
+  completed: boolean;
+  createdAt: number;
+}
+
+// ---------------------------------------------------------------------------
+// Bank schema: config-defined fields.
+// ---------------------------------------------------------------------------
+
+export type BankFieldType = 'text' | 'number' | 'select' | 'multiselect';
+
+export type BankFilterOperatorId =
+  | 'is'
+  | 'isNot'
+  | 'contains'
+  | 'doesNotContain'
+  | 'startsWith'
+  | 'endsWith'
+  | 'eq'
+  | 'neq'
+  | 'gt'
+  | 'lt'
+  | 'gte'
+  | 'lte'
+  | 'between'
+  | 'isEmpty'
+  | 'isNotEmpty';
+
+export interface BankFieldOption {
+  value: string;
+  label: string;
+}
+
+export interface BankFieldDef {
+  /** Stable field id. Reserved: id, title, tags, status. */
+  id: string;
+  label: string;
+  type: BankFieldType;
+  /** Extract the raw value from a question. */
+  getValue: (question: BaseQuestion) => string | number | null | readonly string[];
+  /**
+   * Fixed options for select/multiselect. When omitted, options are derived
+   * from distinct values across the bank's questions (sorted).
+   */
+  options?: readonly BankFieldOption[];
+  placeholder?: string;
+  /** Include in the free-text search index. Defaults to false (id/title/prompt/tags always searched). */
+  searchable?: boolean;
+  /** Allowed operators. Defaults per type (same as Notion-style builder). */
+  operators?: readonly BankFilterOperatorId[];
+  /** Table column behaviour. `false` hides the field from the grid. */
+  column?: false | { header?: string; width?: number; sortable?: boolean };
+}
+
+export interface BankSiteConfig {
+  title: string;
+  /** Header brand text. */
+  brand: string;
+  description?: string;
+}
+
+export interface DefineBankInput {
+  site: BankSiteConfig;
+  /** Namespaces localStorage keys + Convex lookups. e.g. "comp20008". */
+  namespace: string;
+  /** Subject-specific schema. Built-ins (id/title/tags/status) are automatic. */
+  fields: BankFieldDef[];
+  questions: BaseQuestion[];
+  /** Suggested answers keyed by question id. Missing entries hide "Show answer". */
+  answers?: Record<string, string>;
+  /** Default sort for the grid, e.g. [{ id: "exam", desc: true }]. */
+  defaultSorting?: Array<{ id: string; desc?: boolean }>;
+  /** Extra per-question figures, resolved by prompt `![](/figures/…)` etc. */
+  publicPath?: string;
+}
+
+export interface Bank extends DefineBankInput {
+  answers: Record<string, string>;
+  questionById: Map<string, BaseQuestion>;
+}
+
+export function defineBank(input: DefineBankInput): Bank {
+  return {
+    ...input,
+    answers: input.answers ?? {},
+    questionById: new Map(input.questions.map((q) => [q.id, q])),
+  };
+}

package/framework/components/app-shell.tsx

@@ -0,0 +1,54 @@
+// Framework-owned: eject with `qb reveal framework/components/app-shell.tsx`.
+// Generic header: brand + nav come from the bank, not hardcoded "fieldnotes".
+
+import { Link, useRouterState } from '@tanstack/react-router';
+import type { ReactNode } from 'react';
+import { cn } from '../lib/utils.ts';
+
+export function AppShell({
+  children,
+  brand,
+  homeLabel = 'Question bank',
+  quizzesLabel = 'My quizzes',
+}: {
+  children: ReactNode;
+  brand: string;
+  homeLabel?: string;
+  quizzesLabel?: string;
+}) {
+  const pathname = useRouterState({ select: (state) => state.location.pathname });
+  const navigation = [
+    { label: homeLabel, to: '/' },
+    { label: quizzesLabel, to: '/quizzes' },
+  ] as const;
+  const isQuestionBank = pathname === '/';
+
+  return (
+    <div className={cn('flex flex-col bg-white', isQuestionBank ? 'h-dvh overflow-hidden' : 'min-h-dvh')}>
+      <header className="sticky top-0 z-20 shrink-0 border-b border-gray-200 bg-white">
+        <div className="mx-auto flex h-16 w-full max-w-6xl items-center gap-8 px-4">
+          <Link to="/" className="text-lg font-bold text-gray-900">
+            {brand}
+          </Link>
+          <nav className="flex items-center gap-6" aria-label="Main navigation">
+            {navigation.map(({ label, to }) => {
+              const active = to === '/' ? pathname === '/' : pathname.startsWith(to);
+              return (
+                <Link
+                  key={to}
+                  to={to}
+                  className={cn('text-sm font-semibold text-gray-600 hover:text-gray-900', active && 'text-gray-900 underline underline-offset-4')}
+                >
+                  {label}
+                </Link>
+              );
+            })}
+          </nav>
+        </div>
+      </header>
+      <main className={cn('w-full flex-1', isQuestionBank ? 'flex min-h-0 flex-col overflow-hidden' : 'mx-auto max-w-6xl px-4 py-8')}>
+        {children}
+      </main>
+    </div>
+  );
+}