fix: extract shared domain logic, fix MCP npm install failure (#100)

The published @graspful/mcp@0.2.3 shipped with workspace:* for the
@graspful/shared dep, causing npm install to fail with EUNSUPPORTEDPROTOCOL.

Root cause: the CI sed replacement ran but MCP version was never bumped
after the prior fix (de7036f only bumped CLI).

Fix: move duplicated domain logic (validate, describe, scaffold,
fill-concept, quality gate) from MCP and CLI into @graspful/shared.
Both packages now import from shared instead of maintaining copies.

- @graspful/shared 0.2.2 -> 0.2.3 (new exports)
- @graspful/mcp 0.2.3 -> 0.2.4 (fix burned version)
- @graspful/cli 0.2.5 -> 0.2.6 (uses shared imports)
- MCP index.ts: 1271 -> 541 lines
- Net: -680 lines of duplicated code

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: willwearing

packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graspful/cli",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "description": "Create adaptive learning courses from YAML. CLI and MCP server for AI agents.",
   "keywords": ["course", "learning", "adaptive", "mcp", "mcp-server", "ai", "ai-agent", "agent", "cli", "education", "edtech", "knowledge-graph", "spaced-repetition", "course-creation", "yaml", "adaptive-learning", "lms"],
   "repository": {

packages/cli/src/commands/create-brand.ts

@@ -1,74 +1,10 @@
 import { Command } from 'commander';
 import * as fs from 'fs';
 import * as yaml from 'js-yaml';
+import { scaffoldBrandObject } from '@graspful/shared';
 import { output } from '../lib/output';
 import { cliCapture } from '../lib/analytics';
 
-const NICHE_PRESETS: Record<string, { preset: string; tagline: string; headline: string }> = {
-  education: { preset: 'blue', tagline: 'Learn smarter, not harder', headline: 'Master any subject with adaptive learning' },
-  healthcare: { preset: 'emerald', tagline: 'Training that saves lives', headline: 'Adaptive healthcare education for professionals' },
-  finance: { preset: 'slate', tagline: 'Build financial expertise', headline: 'Master finance with adaptive learning' },
-  tech: { preset: 'indigo', tagline: 'Level up your skills', headline: 'Adaptive tech training that meets you where you are' },
-  legal: { preset: 'amber', tagline: 'Know the law, pass the exam', headline: 'Adaptive legal education for exam success' },
-  default: { preset: 'blue', tagline: 'Learn adaptively', headline: 'Personalized learning that works' },
-};
-
-export function scaffoldBrand(niche: string, options: { name?: string; domain?: string; orgSlug?: string }): string {
-  const config = NICHE_PRESETS[niche] || NICHE_PRESETS['default'];
-  const slug = (options.name || niche).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
-  const name = options.name || `${niche.charAt(0).toUpperCase() + niche.slice(1)} Academy`;
-  const domain = options.domain || `${slug}.graspful.ai`;
-
-  return yaml.dump({
-    brand: {
-      id: slug,
-      name,
-      domain,
-      tagline: config.tagline,
-      logoUrl: '/icon.svg',
-      orgSlug: options.orgSlug || 'TODO: your-org-slug',
-    },
-    theme: {
-      preset: config.preset,
-      radius: '0.5rem',
-    },
-    landing: {
-      hero: {
-        headline: config.headline,
-        subheadline: `${name} uses adaptive learning to help you master concepts faster.`,
-        ctaText: 'Start Learning',
-      },
-      features: {
-        heading: 'Why choose us?',
-        items: [
-          { title: 'Adaptive Learning', description: 'Content adapts to your knowledge level', icon: 'brain' },
-          { title: 'Spaced Repetition', description: 'Review at optimal intervals for lasting memory', icon: 'clock' },
-          { title: 'Progress Tracking', description: 'See exactly where you stand', icon: 'chart' },
-        ],
-      },
-      howItWorks: {
-        heading: 'How it works',
-        items: [
-          { title: 'Take a diagnostic', description: 'We assess what you already know' },
-          { title: 'Learn adaptively', description: 'Focus on gaps, skip what you know' },
-          { title: 'Master the material', description: 'Prove mastery through progressive challenges' },
-        ],
-      },
-      faq: [],
-    },
-    pricing: {
-      monthly: 0,
-      currency: 'usd',
-      trialDays: 0,
-    },
-    seo: {
-      title: `${name} — Adaptive Learning`,
-      description: config.tagline,
-      keywords: [niche, 'learning', 'adaptive', 'education'],
-    },
-  }, { lineWidth: 120, noRefs: true });
-}
-
 export function registerCreateBrandCommand(createCmd: Command) {
   createCmd
     .command('brand')
@@ -79,11 +15,12 @@ export function registerCreateBrandCommand(createCmd: Command) {
     .option('--org <slug>', 'Organization slug')
     .option('-o, --output <file>', 'Output file path (defaults to stdout)')
     .action(async (opts: { niche: string; name?: string; domain?: string; org?: string; output?: string }) => {
-      const yamlContent = scaffoldBrand(opts.niche, {
+      const obj = scaffoldBrandObject(opts.niche, {
         name: opts.name,
         domain: opts.domain,
         orgSlug: opts.org,
       });
+      const yamlContent = yaml.dump(obj, { lineWidth: 120, noRefs: true });
 
       cliCapture('brand scaffolded', { niche: opts.niche });
       if (opts.output) {

packages/cli/src/commands/create-course.ts

@@ -1,39 +1,10 @@
 import { Command } from 'commander';
 import * as fs from 'fs';
 import * as yaml from 'js-yaml';
-import { output, outputError } from '../lib/output';
+import { scaffoldCourseObject } from '@graspful/shared';
+import { output } from '../lib/output';
 import { cliCapture } from '../lib/analytics';
 
-export function scaffoldCourse(topic: string, options: { hours?: number; source?: string }): string {
-  const slug = topic.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
-  return yaml.dump({
-    course: {
-      id: slug,
-      name: topic,
-      description: `Adaptive course on ${topic}`,
-      estimatedHours: options.hours || 10,
-      version: '2026.1',
-      sourceDocument: options.source || 'TODO: Add source document',
-    },
-    sections: [
-      { id: 'foundations', name: 'Foundations', description: 'Core concepts' },
-      { id: 'application', name: 'Application', description: 'Applied concepts' },
-    ],
-    concepts: [
-      {
-        id: `${slug}-intro`,
-        name: `Introduction to ${topic}`,
-        section: 'foundations',
-        difficulty: 2,
-        estimatedMinutes: 15,
-        tags: ['foundational'],
-        prerequisites: [],
-        knowledgePoints: [],
-      },
-    ],
-  }, { lineWidth: 120, noRefs: true });
-}
-
 export function registerCreateCourseCommand(program: Command) {
   const create = program
     .command('create')
@@ -48,10 +19,11 @@ export function registerCreateCourseCommand(program: Command) {
     .option('-o, --output <file>', 'Output file path (defaults to stdout)')
     .option('--scaffold-only', 'Generate scaffold without AI enrichment', true)
     .action(async (opts: { topic: string; hours: string; source?: string; output?: string; scaffoldOnly: boolean }) => {
-      const yamlContent = scaffoldCourse(opts.topic, {
+      const obj = scaffoldCourseObject(opts.topic, {
         hours: parseInt(opts.hours, 10),
         source: opts.source,
       });
+      const yamlContent = yaml.dump(obj, { lineWidth: 120, noRefs: true });
 
       cliCapture('course scaffolded', { topic: opts.topic, estimated_hours: parseInt(opts.hours, 10) });
 
@@ -62,7 +34,6 @@ export function registerCreateCourseCommand(program: Command) {
           `Scaffold written to ${opts.output}`,
         );
       } else {
-        // Output raw YAML to stdout (not wrapped in JSON even in json mode for piping)
         console.log(yamlContent);
       }
     });

packages/cli/src/commands/describe.ts

@@ -1,44 +1,10 @@
 import { Command } from 'commander';
 import * as fs from 'fs';
 import * as yaml from 'js-yaml';
-import { CourseYamlSchema } from '@graspful/shared';
-import type { CourseYaml } from '@graspful/shared';
+import { CourseYamlSchema, describeCourse } from '@graspful/shared';
 import { output, outputError } from '../lib/output';
 import { cliCapture } from '../lib/analytics';
 
-function computeGraphDepth(concepts: CourseYaml['concepts']): number {
-  const graph = new Map<string, string[]>();
-  for (const c of concepts) {
-    graph.set(c.id, c.prerequisites);
-  }
-
-  const memo = new Map<string, number>();
-
-  function depth(id: string, visited: Set<string>): number {
-    if (memo.has(id)) return memo.get(id)!;
-    if (visited.has(id)) return 0; // cycle, avoid infinite loop
-    visited.add(id);
-
-    const prereqs = graph.get(id) ?? [];
-    let maxPrereqDepth = 0;
-    for (const prereq of prereqs) {
-      if (graph.has(prereq)) {
-        maxPrereqDepth = Math.max(maxPrereqDepth, depth(prereq, visited));
-      }
-    }
-
-    const d = maxPrereqDepth + 1;
-    memo.set(id, d);
-    return d;
-  }
-
-  let maxDepth = 0;
-  for (const c of concepts) {
-    maxDepth = Math.max(maxDepth, depth(c.id, new Set()));
-  }
-  return maxDepth;
-}
-
 export function registerDescribeCommand(program: Command) {
   program
     .command('describe <file>')
@@ -64,89 +30,25 @@ export function registerDescribeCommand(program: Command) {
         process.exit(1);
       }
 
-      const data = result.data;
-      const concepts = data.concepts;
-      const sections = data.sections;
-
-      const authoredConcepts = concepts.filter((c) => c.knowledgePoints.length > 0);
-      const stubConcepts = concepts.filter((c) => c.knowledgePoints.length === 0);
-
-      const kpCount = concepts.reduce((sum, c) => sum + c.knowledgePoints.length, 0);
-      const problemCount = concepts.reduce(
-        (sum, c) => sum + c.knowledgePoints.reduce((s, kp) => s + kp.problems.length, 0),
-        0,
-      );
-
-      const graphDepth = computeGraphDepth(concepts);
-
-      const conceptsWithoutKps = stubConcepts.map((c) => c.id);
-      const kpsWithoutProblems: string[] = [];
-      for (const c of concepts) {
-        for (const kp of c.knowledgePoints) {
-          if (kp.problems.length === 0) {
-            kpsWithoutProblems.push(`${c.id}/${kp.id}`);
-          }
-        }
-      }
-
-      // Section breakdown
-      const sectionBreakdown: Array<{ section: string; concepts: number; kps: number; problems: number }> = [];
-      if (sections.length > 0) {
-        for (const section of sections) {
-          const sectionConcepts = concepts.filter((c) => c.section === section.id);
-          const sKps = sectionConcepts.reduce((sum, c) => sum + c.knowledgePoints.length, 0);
-          const sProblems = sectionConcepts.reduce(
-            (sum, c) => sum + c.knowledgePoints.reduce((s, kp) => s + kp.problems.length, 0),
-            0,
-          );
-          sectionBreakdown.push({ section: section.id, concepts: sectionConcepts.length, kps: sKps, problems: sProblems });
-        }
-
-        // Concepts without a section
-        const unsectioned = concepts.filter((c) => !c.section);
-        if (unsectioned.length > 0) {
-          const uKps = unsectioned.reduce((sum, c) => sum + c.knowledgePoints.length, 0);
-          const uProblems = unsectioned.reduce(
-            (sum, c) => sum + c.knowledgePoints.reduce((s, kp) => s + kp.problems.length, 0),
-            0,
-          );
-          sectionBreakdown.push({ section: '(unsectioned)', concepts: unsectioned.length, kps: uKps, problems: uProblems });
-        }
-      }
-
-      const stats = {
-        courseName: data.course.name,
-        courseId: data.course.id,
-        version: data.course.version,
-        estimatedHours: data.course.estimatedHours,
-        concepts: concepts.length,
-        authoredConcepts: authoredConcepts.length,
-        stubConcepts: stubConcepts.length,
-        knowledgePoints: kpCount,
-        problems: problemCount,
-        graphDepth,
-        conceptsWithoutKps: conceptsWithoutKps.length,
-        kpsWithoutProblems: kpsWithoutProblems.length,
-        sections: sectionBreakdown,
-      };
+      const stats = describeCourse(result.data);
 
       const humanLines = [
-        `Course: "${data.course.name}" (v${data.course.version})`,
-        `Concepts: ${concepts.length} (${authoredConcepts.length} authored, ${stubConcepts.length} stubs)`,
-        `KPs: ${kpCount}, Problems: ${problemCount}`,
-        `Graph depth: ${graphDepth}`,
-        `Missing: ${conceptsWithoutKps.length} concepts need KPs, ${kpsWithoutProblems.length} KPs need problems`,
+        `Course: "${stats.courseName}" (v${stats.version})`,
+        `Concepts: ${stats.concepts} (${stats.authoredConcepts} authored, ${stats.stubConcepts} stubs)`,
+        `KPs: ${stats.knowledgePoints}, Problems: ${stats.problems}`,
+        `Graph depth: ${stats.graphDepth}`,
+        `Missing: ${stats.conceptsWithoutKps} concepts need KPs, ${stats.kpsWithoutProblems} KPs need problems`,
       ];
 
-      if (sectionBreakdown.length > 0) {
+      if (stats.sections.length > 0) {
         humanLines.push('');
         humanLines.push('Sections:');
-        for (const s of sectionBreakdown) {
+        for (const s of stats.sections) {
           humanLines.push(`  ${s.section}: ${s.concepts} concepts, ${s.kps} KPs, ${s.problems} problems`);
         }
       }
 
-      cliCapture('course described', { concept_count: concepts.length, kp_count: kpCount, problem_count: problemCount });
+      cliCapture('course described', { concept_count: stats.concepts, kp_count: stats.knowledgePoints, problem_count: stats.problems });
       output(stats, humanLines.join('\n'));
     });
 }

packages/cli/src/commands/fill-concept.ts

@@ -1,7 +1,7 @@
 import { Command } from 'commander';
 import * as fs from 'fs';
 import * as yaml from 'js-yaml';
-import { CourseYamlSchema } from '@graspful/shared';
+import { fillConceptInRaw } from '@graspful/shared';
 import { output, outputError } from '../lib/output';
 import { cliCapture } from '../lib/analytics';
 
@@ -31,69 +31,24 @@ export function registerFillConceptCommand(program: Command) {
         process.exit(1);
       }
 
-      const parsed = CourseYamlSchema.safeParse(raw);
-      if (!parsed.success) {
-        outputError(`Invalid course YAML: ${parsed.error.issues[0]?.message ?? 'unknown error'}`);
-        process.exit(1);
-      }
+      try {
+        const updated = fillConceptInRaw(raw, conceptId, {
+          kps: parseInt(opts.kps, 10),
+          problemsPerKp: parseInt(opts.problems, 10),
+        });
 
-      const data = parsed.data;
-      const concept = data.concepts.find((c) => c.id === conceptId);
-      if (!concept) {
-        outputError(`Concept "${conceptId}" not found. Available: ${data.concepts.map((c) => c.id).join(', ')}`);
-        process.exit(1);
-      }
+        const updatedYaml = yaml.dump(updated, { lineWidth: 120, noRefs: true, schema: yaml.JSON_SCHEMA });
+        fs.writeFileSync(file, updatedYaml);
 
-      if (concept.knowledgePoints.length > 0) {
+        cliCapture('concept filled', { concept_id: conceptId });
         output(
-          { conceptId, existingKps: concept.knowledgePoints.length, action: 'skipped' },
-          `Concept "${conceptId}" already has ${concept.knowledgePoints.length} KP(s). Use --force to overwrite (not yet implemented).`,
+          { conceptId, kpsAdded: parseInt(opts.kps, 10), problemsPerKp: parseInt(opts.problems, 10), file },
+          `Added ${opts.kps} KP stub(s) with ${opts.problems} problem(s) each to "${conceptId}" in ${file}`,
         );
-        return;
-      }
-
-      const kpCount = parseInt(opts.kps, 10);
-      const problemsPerKp = parseInt(opts.problems, 10);
-
-      const newKps = [];
-      for (let i = 1; i <= kpCount; i++) {
-        const problems = [];
-        for (let j = 1; j <= problemsPerKp; j++) {
-          problems.push({
-            id: `${conceptId}-kp${i}-p${j}`,
-            type: 'multiple_choice',
-            question: `TODO: Write question ${j} for ${conceptId} KP${i}`,
-            options: ['Option A', 'Option B', 'Option C', 'Option D'],
-            correct: 0,
-            explanation: 'TODO: Explain the correct answer',
-            difficulty: Math.min(j + 1, 5),
-          });
-        }
-
-        newKps.push({
-          id: `${conceptId}-kp${i}`,
-          instruction: `TODO: Write instruction for ${concept.name} — knowledge point ${i}`,
-          workedExample: `TODO: Write a worked example for ${concept.name} — knowledge point ${i}`,
-          problems,
-        });
-      }
-
-      // Rebuild the raw object to preserve structure, then replace the concept's KPs
-      const rawObj = raw as Record<string, unknown>;
-      const concepts = (rawObj['concepts'] as Array<Record<string, unknown>>);
-      const targetConcept = concepts.find((c) => c['id'] === conceptId);
-      if (targetConcept) {
-        targetConcept['knowledgePoints'] = newKps;
+      } catch (e) {
+        outputError(e instanceof Error ? e.message : String(e));
+        process.exit(1);
       }
-
-      const updatedYaml = yaml.dump(rawObj, { lineWidth: 120, noRefs: true, schema: yaml.JSON_SCHEMA });
-      fs.writeFileSync(file, updatedYaml);
-
-      cliCapture('concept filled', { concept_id: conceptId });
-      output(
-        { conceptId, kpsAdded: kpCount, problemsPerKp, file },
-        `Added ${kpCount} KP stub(s) with ${problemsPerKp} problem(s) each to "${conceptId}" in ${file}`,
-      );
     });
 
   return fill;