@aabadin/didactic-ppt-skill-package 0.1.0

package/README.md

@@ -0,0 +1,38 @@
+# didactic-ppt-skill-package
+
+Installs the `didactic-powerpoint-pedagogico` OpenCode skill into:
+
+- `~/.config/opencode/skills/didactic-powerpoint-pedagogico/`
+
+## Example workflow
+
+1. Install with `npx --yes @aabadin/didactic-ppt-skill-package`.
+2. Restart OpenCode.
+3. Ask for a didactic `.pptx` from educational source text.
+
+Example prompt:
+
+```text
+Create a didactic PowerPoint from this educational source text and save it as a .pptx.
+```
+
+## Local generation example
+
+```bash
+node .\skills\didactic-powerpoint-pedagogico\scripts\cli.js .\tests\fixtures\flow-input.txt .\output\flujo-didactico.pptx
+```
+
+## Local package install test
+
+```bash
+npx --yes .\didactic-ppt-skill-package
+```
+
+## Publish to npm
+
+```bash
+npm login
+npm publish
+```
+
+The package is already configured with `publishConfig.access = public`, which is required for initial publication of a public scoped package such as `@aabadin/didactic-ppt-skill-package`.

package/bin/install.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const skillName = 'didactic-powerpoint-pedagogico';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const sourceDir = path.join(__dirname, '..', 'skills', skillName);
+const targetDir = path.join(os.homedir(), '.config', 'opencode', 'skills', skillName);
+
+function installSkillDependencies(directory) {
+  const command = process.platform === 'win32'
+    ? process.env.ComSpec ?? 'cmd.exe'
+    : 'npm';
+  const args = process.platform === 'win32'
+    ? ['/d', '/s', '/c', 'npm install --omit=dev']
+    : ['install', '--omit=dev'];
+  const result = spawnSync(command, args, {
+    cwd: directory,
+    stdio: 'inherit'
+  });
+
+  if (result.error) {
+    console.error(`Failed to install ${skillName} dependencies: ${result.error.message}`);
+    process.exit(1);
+  }
+
+  if (result.status !== 0) {
+    process.exit(result.status ?? 1);
+  }
+}
+
+if (!fs.existsSync(sourceDir)) {
+  console.error(`Skill source not found: ${sourceDir}`);
+  process.exitCode = 1;
+} else {
+  fs.mkdirSync(targetDir, { recursive: true });
+  fs.cpSync(sourceDir, targetDir, { recursive: true, force: true });
+  installSkillDependencies(targetDir);
+
+  console.log(`Installed ${skillName} to ${targetDir}`);
+  console.log('Restart OpenCode so new sessions can detect the skill.');
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@aabadin/didactic-ppt-skill-package",
+  "version": "0.1.0",
+  "description": "Install the didactic-powerpoint-pedagogico OpenCode skill into the global skills directory.",
+  "type": "module",
+  "bin": {
+    "didactic-ppt-skill-package": "bin/install.js"
+  },
+  "scripts": {
+    "test": "node --test",
+    "pack:check": "npm pack --dry-run"
+  },
+  "dependencies": {
+    "pptxgenjs": "^3.12.0"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "bin",
+    "skills",
+    "README.md"
+  ],
+  "keywords": [
+    "opencode",
+    "skill",
+    "powerpoint",
+    "pptx",
+    "didactic",
+    "education"
+  ],
+  "author": "aabadin",
+  "license": "UNLICENSED"
+}

package/skills/didactic-powerpoint-pedagogico/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: didactic-powerpoint-pedagogico
+description: Use when the user asks to create, redesign, or generate a didactic presentation, educational slide deck, teaching slides, or a .pptx from source text. Use even if the user mainly asks for more pedagogical, more legible, more projection-safe, or more structured teaching slides.
+---
+
+# Didactic PowerPoint Pedagogico
+
+## When to Use
+
+Use this skill when the output should be a didactic `.pptx` presentation driven by explicit pedagogical structure rather than decorative slide design.
+
+Consult `references/pedagogical-rules.md` for the pedagogical constraints and `templates/didactic-theme.json` for the packaged typography, color, and grid defaults.
+
+## Workflow
+
+1. Parse the source text into one idea per slide.
+2. Convert each slide into an assertion-evidence structure.
+3. Select one deterministic diagram family: `flow`, `network`, `segment`, `stack`, or `join`.
+4. Build an intermediate slide spec.
+5. Validate typography, fit, contrast, and object-count rules.
+6. Generate the `.pptx`.
+
+## Hard Rules
+
+- Use only sans-serif typography.
+- Never shrink body text below `16 pt`.
+- Keep titles within two lines.
+- Keep slides within six independent visual objects.
+- Split or simplify slides instead of allowing overflow.
+
+## Output Contract
+
+- Produce a `.pptx` file.
+- Report validation adjustments when content was shortened, split, or simplified.
+- Prefer segmentation over illegible compression.

package/skills/didactic-powerpoint-pedagogico/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "didactic-powerpoint-pedagogico",
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "pptxgenjs": "^3.12.0"
+  }
+}

package/skills/didactic-powerpoint-pedagogico/references/pedagogical-rules.md

@@ -0,0 +1,10 @@
+# Pedagogical Rules
+
+- Assertion-evidence titles only
+- One central idea per slide
+- Max six independent objects
+- Deterministic diagram mapping
+- Grid 4x3 plus whitespace preservation
+- Left-aligned sans-serif typography
+- Minimum contrast ratio 4.5:1
+- Bullet avoidance and overflow prevention

package/skills/didactic-powerpoint-pedagogico/scripts/build-slide-spec.js

@@ -0,0 +1,77 @@
+const DIAGRAM_PATTERNS = {
+  flow: [
+    /\bprimero\b/i,
+    /\bluego\b/i,
+    /\bdespu(?:e|é)s\b/i,
+    /\bfinalmente\b/i,
+    /\bpasos?\b/i,
+    /\bsecuencia\b/i
+  ],
+  network: [
+    /\bniveles\b/i,
+    /\bjer(?:a|á)rqu(?:i|í)(?:a|as|co|ca|cos|cas)\b/i,
+    /\bdepende(?:n)?\b/i,
+    /\bincluye(?:n)?\b/i,
+    /\bramas\b/i,
+    /\bsistema\b/i
+  ],
+  segment: [/\btipos\b/i, /\bcategor(?:i|í)as\b/i, /\bgrupos\b/i],
+  stack: [/\bcapas\b/i, /\bniveles superpuestos\b/i, /\bestratos\b/i],
+  join: [/\bcomparte(?:n)?\b/i, /\bconverge(?:n)?\b/i, /\buni(?:o|ó)n\b/i]
+};
+
+export function buildAssertionTitle(text) {
+  const trimmed = text.trim();
+  const fallbackTitle = 'Esta idea central debe explicarse con evidencia.';
+
+  if (!trimmed) {
+    return fallbackTitle;
+  }
+
+  const boundaryMatch = trimmed.match(/[:;\n]|[.!?]/);
+  if (boundaryMatch) {
+    const boundaryIndex = boundaryMatch.index;
+    const boundary = boundaryMatch[0];
+    const sliceEnd = /[.!?]/.test(boundary) ? boundaryIndex + 1 : boundaryIndex;
+    const title = trimmed.slice(0, sliceEnd).trim();
+
+    if (title) {
+      return title;
+    }
+  }
+
+  return trimmed || fallbackTitle;
+}
+
+function inferDiagramType(text) {
+  for (const [diagramType, patterns] of Object.entries(DIAGRAM_PATTERNS)) {
+    if (patterns.some((pattern) => pattern.test(text))) {
+      return diagramType;
+    }
+  }
+
+  return 'join';
+}
+
+export function buildSlideSpec(sourceText) {
+  const trimmedText = sourceText.trim();
+
+  return {
+    theme: 'didactic-default',
+    slides: [
+      {
+        assertionTitle: buildAssertionTitle(trimmedText),
+        contentStructure: 'auto',
+        diagramType: inferDiagramType(trimmedText),
+        canvas: 'grid-4x3',
+        elements: [
+          {
+            type: 'shape',
+            role: 'concept',
+            text: trimmedText
+          }
+        ]
+      }
+    ]
+  };
+}

package/skills/didactic-powerpoint-pedagogico/scripts/cli.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+
+import { buildSlideSpec } from './build-slide-spec.js';
+import { generatePptx } from './generate-pptx.js';
+
+const inputPath = process.argv[2];
+const outputPath = process.argv[3] ?? path.resolve('didactic-presentation.pptx');
+
+if (!inputPath) {
+  console.error('Usage: node cli.js <input.txt> [output.pptx]');
+  process.exitCode = 1;
+} else {
+  try {
+    const sourceText = await readFile(inputPath, 'utf8');
+    const spec = buildSlideSpec(sourceText);
+    await generatePptx(spec, outputPath);
+    console.log(`Generated ${outputPath}`);
+  } catch (error) {
+    console.error(error.message);
+    process.exitCode = 1;
+  }
+}

package/skills/didactic-powerpoint-pedagogico/scripts/fit-text.js

@@ -0,0 +1,36 @@
+export const MIN_FONT_SIZE = 16;
+
+function estimateCapacity(box, fontSize) {
+  const width = Math.max(0, Number(box?.width) || 0);
+  const height = Math.max(0, Number(box?.height) || 0);
+
+  if (width === 0 || height === 0) {
+    return 0;
+  }
+
+  const charsPerLine = Math.max(1, Math.floor(width / (fontSize * 0.6)));
+  const lineCount = Math.max(1, Math.floor(height / (fontSize * 1.2)));
+  return charsPerLine * lineCount;
+}
+
+export function fitText(text, box) {
+  const normalizedText = String(text ?? '').trim();
+  const baseFontSize = Number(box?.fontSize) || Math.floor((Number(box?.height) || 0) / 3);
+  const fontSize = Math.max(MIN_FONT_SIZE, baseFontSize);
+  const capacity = estimateCapacity(box, fontSize);
+
+  if (capacity === 0 || normalizedText.length <= capacity) {
+    return { text: normalizedText, fontSize, overflow: false, truncated: false };
+  }
+
+  const compressedText = capacity <= 3
+    ? normalizedText.slice(0, capacity)
+    : `${normalizedText.slice(0, capacity - 3).trimEnd()}...`;
+
+  return {
+    text: compressedText,
+    fontSize,
+    overflow: false,
+    truncated: true
+  };
+}

package/skills/didactic-powerpoint-pedagogico/scripts/generate-pptx.js

@@ -0,0 +1,108 @@
+import PptxGenJS from 'pptxgenjs';
+import { mkdir } from 'node:fs/promises';
+import path from 'node:path';
+import theme from '../templates/didactic-theme.json' with { type: 'json' };
+
+import { fitText } from './fit-text.js';
+import { validateSlide } from './validate-layout.js';
+
+const BACKGROUND_COLOR = theme.colors.background;
+const TEXT_COLOR = theme.colors.text;
+const BODY_FILL_COLOR = theme.colors.surface;
+const BODY_LINE_COLOR = theme.colors.surfaceLine;
+const TITLE_FONT_SIZE = theme.titleFontSize;
+const BODY_FONT_SIZE = theme.bodyFontSize;
+const FONT_FACE = theme.fontFace;
+const BODY_TEXT_BOX = Object.freeze({
+  width: 396,
+  height: 86.4,
+  fontSize: BODY_FONT_SIZE,
+  color: TEXT_COLOR,
+  backgroundColor: BODY_FILL_COLOR
+});
+
+function getBodyText(slideSpec) {
+  return slideSpec.elements?.[0]?.text ?? '';
+}
+
+function prepareSlideForRendering(slideSpec) {
+  const elements = Array.isArray(slideSpec?.elements) ? slideSpec.elements : [];
+  const [firstElement, ...restElements] = elements;
+
+  if (!firstElement) {
+    return { ...slideSpec, elements };
+  }
+
+  const bodyElement = {
+    ...BODY_TEXT_BOX,
+    ...firstElement
+  };
+  const fittedText = fitText(bodyElement.text, {
+    width: bodyElement.width,
+    height: bodyElement.height,
+    fontSize: bodyElement.fontSize
+  });
+
+  return {
+    ...slideSpec,
+    elements: [
+      {
+        ...bodyElement,
+        ...fittedText
+      },
+      ...restElements
+    ]
+  };
+}
+
+export async function generatePptx(spec, outputPath) {
+  const pptx = new PptxGenJS();
+  pptx.layout = 'LAYOUT_WIDE';
+  const validationIssues = [];
+
+  for (const [slideIndex, slideSpec] of (spec.slides ?? []).entries()) {
+    const preparedSlide = prepareSlideForRendering(slideSpec);
+    const issues = validateSlide(preparedSlide);
+
+    if (issues.length > 0) {
+      validationIssues.push({ slideIndex, issues });
+    }
+
+    const slide = pptx.addSlide();
+
+    slide.background = { color: BACKGROUND_COLOR };
+
+    slide.addText(preparedSlide.assertionTitle ?? '', {
+      x: 0.4,
+      y: 0.3,
+      w: 12,
+      h: 0.8,
+      fontFace: FONT_FACE,
+      fontSize: TITLE_FONT_SIZE,
+      bold: true,
+      color: TEXT_COLOR,
+      align: 'left',
+      margin: 0
+    });
+
+    slide.addText(getBodyText(preparedSlide), {
+      shape: pptx.ShapeType.rect,
+      x: 0.8,
+      y: 1.8,
+      w: 5.5,
+      h: 1.2,
+      fontFace: FONT_FACE,
+      fontSize: BODY_FONT_SIZE,
+      color: TEXT_COLOR,
+      fill: { color: BODY_FILL_COLOR },
+      line: { color: BODY_LINE_COLOR },
+      valign: 'mid',
+      margin: 0.12
+    });
+  }
+
+  await mkdir(path.dirname(outputPath), { recursive: true });
+  await pptx.writeFile({ fileName: outputPath });
+
+  return { outputPath, validationIssues };
+}

package/skills/didactic-powerpoint-pedagogico/scripts/validate-layout.js

@@ -0,0 +1,86 @@
+const MAX_OBJECTS_PER_SLIDE = 6;
+const MAX_ASSERTION_TITLE_LENGTH = 90;
+const MIN_FONT_SIZE = 16;
+const MIN_CONTRAST_RATIO = 4.5;
+
+function parseHexColor(color) {
+  if (typeof color !== 'string') {
+    return null;
+  }
+
+  const normalized = color.trim().replace(/^#/, '');
+  if (!/^[0-9a-fA-F]{6}$/.test(normalized)) {
+    return null;
+  }
+
+  return {
+    r: parseInt(normalized.slice(0, 2), 16),
+    g: parseInt(normalized.slice(2, 4), 16),
+    b: parseInt(normalized.slice(4, 6), 16)
+  };
+}
+
+function channelToLinear(channel) {
+  const normalized = channel / 255;
+  return normalized <= 0.04045
+    ? normalized / 12.92
+    : ((normalized + 0.055) / 1.055) ** 2.4;
+}
+
+function contrastRatio(foreground, background) {
+  const fg = parseHexColor(foreground);
+  const bg = parseHexColor(background);
+
+  if (!fg || !bg) {
+    return null;
+  }
+
+  const fgLuminance = 0.2126 * channelToLinear(fg.r)
+    + 0.7152 * channelToLinear(fg.g)
+    + 0.0722 * channelToLinear(fg.b);
+  const bgLuminance = 0.2126 * channelToLinear(bg.r)
+    + 0.7152 * channelToLinear(bg.g)
+    + 0.0722 * channelToLinear(bg.b);
+
+  const lighter = Math.max(fgLuminance, bgLuminance);
+  const darker = Math.min(fgLuminance, bgLuminance);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+
+export function validateSlide(slide) {
+  const issues = [];
+  const elementCount = Array.isArray(slide?.elements) ? slide.elements.length : 0;
+  const assertionTitle = String(slide?.assertionTitle ?? '').trim();
+
+  // Task 4 scope only: this validator checks metadata-level count, title, fit, and simple contrast hints.
+  // Broader rendering/layout integration is deferred to later generation tasks.
+
+  if (elementCount + 1 > MAX_OBJECTS_PER_SLIDE) {
+    issues.push('Slide has too many objects for the didactic layout.');
+  }
+
+  if (assertionTitle.length > MAX_ASSERTION_TITLE_LENGTH) {
+    issues.push('Assertion title is too long for the didactic layout.');
+  }
+
+  for (const element of Array.isArray(slide?.elements) ? slide.elements : []) {
+    if (typeof element?.fontSize === 'number' && element.fontSize < MIN_FONT_SIZE) {
+      issues.push('Text box font size is below the didactic minimum.');
+    }
+
+    if (element?.overflow === true) {
+      issues.push('Text box is marked as overflowing.');
+    }
+
+    if (element?.truncated === true) {
+      issues.push('Text box content was truncated to fit the didactic layout.');
+    }
+
+    const ratio = contrastRatio(element?.color, element?.backgroundColor);
+    if (typeof ratio === 'number' && ratio < MIN_CONTRAST_RATIO) {
+      issues.push('Text contrast is below 4.5:1 for the didactic layout.');
+    }
+  }
+
+  return issues;
+}

package/skills/didactic-powerpoint-pedagogico/templates/didactic-theme.json

@@ -0,0 +1,20 @@
+{
+  "fontFace": "Arial",
+  "titleFontSize": 36,
+  "bodyFontSize": 24,
+  "minFontSize": 16,
+  "colors": {
+    "background": "F7F7F7",
+    "text": "1F1F1F",
+    "primary": "2F4F6B",
+    "secondary": "4E5F70",
+    "accent": "9F4E18",
+    "surface": "DDE6ED",
+    "surfaceLine": "355C7D"
+  },
+  "grid": {
+    "columns": 4,
+    "rows": 3,
+    "margin": 0.4
+  }
+}