@assistkick/create 1.7.0 → 1.8.0

package/templates/assistkick-product-system/packages/video/scripts/process_script.ts

@@ -0,0 +1,630 @@
+/**
+ * Processes a video script markdown file:
+ * - Parses :::narration and :::screencapture directives
+ * - Generates TTS audio via ElevenLabs for missing or changed narrations
+ * - Measures audio and video durations
+ * - Writes durations.json and hashes.json to the media directory
+ * - Reports missing video files
+ *
+ * Text changes are detected via SHA-256 hashes stored in hashes.json.
+ * When narration text is edited, the audio is regenerated on the next run.
+ *
+ * Usage:
+ *   tsx scripts/process_script.ts <script.md> --project-id <id> --feature-id <id> [options]
+ *
+ * Options:
+ *   --project-id ID    Project ID (required — resolves media dir)
+ *   --feature-id ID    Feature ID (required — scopes media within project)
+ *   --media-base DIR   Override media base dir (default: /data/workspaces/<projectId>/media)
+ *   --force            Regenerate all audio files, even if they exist
+ *   --voice NAME       ElevenLabs voice name (default: George)
+ *   --voice-id ID      ElevenLabs voice ID (overrides --voice)
+ *   --dry-run          Show what would be generated without calling the API
+ *   --json             Output machine-readable JSON summary (for API integration)
+ *   --list-voices      List available ElevenLabs voices
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
+import { createHash } from "crypto";
+import { join, resolve } from "path";
+import https from "https";
+
+// ── ElevenLabs config ────────────────────────────────────────────────────────
+
+const API_BASE = "api.elevenlabs.io";
+const DEFAULT_MODEL = "eleven_v3";
+const DEFAULT_OUTPUT_FORMAT = "mp3_44100_128";
+const DEFAULT_VOICE_ID = "tnSpp4vdxKPjI9w0GnoV"; // George
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+export type Narration = { id: string; src: string; text: string };
+export type ScreenCapture = { id: string; src: string; description: string };
+
+export type TtsResult = {
+  processed: number;
+  generated: number;
+  skipped: number;
+  errors: string[];
+  durations: Record<string, number>;
+  audioBasePath: string;
+};
+
+type CliArgs = {
+  script: string | null;
+  projectId: string | null;
+  featureId: string | null;
+  mediaBase: string | null;
+  force: boolean;
+  voice: string | null;
+  voiceId: string | null;
+  dryRun: boolean;
+  json: boolean;
+  listVoices: boolean;
+  help: boolean;
+};
+
+export type ProcessScriptOptions = {
+  scriptPath: string;
+  projectId: string;
+  featureId: string;
+  mediaBase?: string;
+  force?: boolean;
+  voiceId?: string;
+  voice?: string;
+  dryRun?: boolean;
+};
+
+// ── Hashing ──────────────────────────────────────────────────────────────────
+
+export function hashText(text: string): string {
+  return createHash("sha256").update(text).digest("hex").slice(0, 16);
+}
+
+function loadHashes(hashesFile: string): Record<string, string> {
+  try {
+    return JSON.parse(readFileSync(hashesFile, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+
+// ── Parse :::narration fenced directives ─────────────────────────────────────
+
+export function parseNarrations(markdown: string): Narration[] {
+  const regex = /:::narration\s+(\S+)\s*\n([\s\S]*?):::/g;
+  const narrations: Narration[] = [];
+  let match;
+  while ((match = regex.exec(markdown)) !== null) {
+    const id = match[1];
+    narrations.push({
+      id,
+      src: `audio/${id}.mp3`,
+      text: match[2].trim().replace(/\n+/g, " "),
+    });
+  }
+  return narrations;
+}
+
+// ── Parse :::screencapture fenced directives ─────────────────────────────────
+
+export function parseScreenCaptures(markdown: string): ScreenCapture[] {
+  const regex = /:::screencapture\s+(\S+)\s*\n([\s\S]*?):::/g;
+  const captures: ScreenCapture[] = [];
+  let match;
+  while ((match = regex.exec(markdown)) !== null) {
+    const id = match[1];
+    captures.push({
+      id,
+      src: `video/${id}.mp4`,
+      description: match[2].trim().replace(/\n+/g, " "),
+    });
+  }
+  return captures;
+}
+
+// ── MP3 duration measurement (pure JS — no ffprobe) ──────────────────────────
+
+const MP3_BITRATES: Record<string, number[]> = {
+  "11": [0, 32, 64, 96, 128, 160, 192, 224, 256, 288, 320, 352, 384, 416, 448],
+  "12": [0, 32, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320, 384],
+  "13": [0, 32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320],
+  "21": [0, 32, 48, 56, 64, 80, 96, 112, 128, 144, 160, 176, 192, 224, 256],
+  "22": [0, 8, 16, 24, 32, 40, 48, 56, 64, 80, 96, 112, 128, 144, 160],
+  "23": [0, 8, 16, 24, 32, 40, 48, 56, 64, 80, 96, 112, 128, 144, 160],
+};
+
+const MP3_SAMPLE_RATES: Record<string, number[]> = {
+  "1": [44100, 48000, 32000],
+  "2": [22050, 24000, 16000],
+  "25": [11025, 12000, 8000],
+};
+
+export function getAudioDuration(filePath: string): number | null {
+  try {
+    const buf = readFileSync(filePath);
+    const fileSize = buf.length;
+
+    // Skip ID3v2 tag if present
+    let offset = 0;
+    if (buf[0] === 0x49 && buf[1] === 0x44 && buf[2] === 0x33) {
+      const tagSize =
+        ((buf[6] & 0x7f) << 21) |
+        ((buf[7] & 0x7f) << 14) |
+        ((buf[8] & 0x7f) << 7) |
+        (buf[9] & 0x7f);
+      offset = 10 + tagSize;
+    }
+
+    // Find first valid MP3 frame
+    while (offset < fileSize - 4) {
+      if (buf[offset] === 0xff && (buf[offset + 1] & 0xe0) === 0xe0) {
+        const header =
+          (buf[offset] << 24) |
+          (buf[offset + 1] << 16) |
+          (buf[offset + 2] << 8) |
+          buf[offset + 3];
+
+        const versionBits = (header >> 19) & 0x03;
+        const layerBits = (header >> 17) & 0x03;
+        const bitrateIdx = (header >> 12) & 0x0f;
+        const sampleIdx = (header >> 10) & 0x03;
+
+        if (
+          versionBits === 1 ||
+          layerBits === 0 ||
+          bitrateIdx === 0 ||
+          bitrateIdx === 15 ||
+          sampleIdx === 3
+        ) {
+          offset++;
+          continue;
+        }
+
+        const versionKey =
+          versionBits === 3 ? "1" : versionBits === 2 ? "2" : "25";
+        const layerKey = 4 - layerBits;
+        const brKey = `${versionBits === 3 ? 1 : 2}${layerKey}`;
+        const bitrate = (MP3_BITRATES[brKey]?.[bitrateIdx] ?? 0) * 1000;
+        const sampleRate = MP3_SAMPLE_RATES[versionKey]?.[sampleIdx] ?? 0;
+
+        if (bitrate > 0 && sampleRate > 0) {
+          const audioBytes = fileSize - offset;
+          const duration = (audioBytes * 8) / bitrate;
+          return Math.round(duration * 100) / 100;
+        }
+      }
+      offset++;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+// ── MP4 duration measurement (pure JS — reads mvhd atom) ─────────────────────
+
+export function getMp4Duration(filePath: string): number | null {
+  try {
+    const buf = readFileSync(filePath);
+    const len = buf.length;
+    let offset = 0;
+
+    while (offset < len - 8) {
+      const size = buf.readUInt32BE(offset);
+      const type = buf.toString("ascii", offset + 4, offset + 8);
+
+      if (size < 8 || offset + size > len) break;
+
+      // Recurse into container atoms
+      if (type === "moov" || type === "trak" || type === "mdia") {
+        offset += 8;
+        continue;
+      }
+
+      if (type === "mvhd") {
+        const version = buf[offset + 8];
+        let timescale: number;
+        let duration: number;
+
+        if (version === 0) {
+          timescale = buf.readUInt32BE(offset + 20);
+          duration = buf.readUInt32BE(offset + 24);
+        } else {
+          timescale = buf.readUInt32BE(offset + 28);
+          const high = buf.readUInt32BE(offset + 32);
+          const low = buf.readUInt32BE(offset + 36);
+          duration = high * 0x100000000 + low;
+        }
+
+        if (timescale > 0) {
+          return Math.round((duration / timescale) * 100) / 100;
+        }
+        return null;
+      }
+
+      offset += size;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+// ── ElevenLabs API ───────────────────────────────────────────────────────────
+
+function loadApiKey(): string {
+  const key = process.env.ELEVENLABS_API_KEY;
+  if (key) return key;
+
+  console.error("Error: ELEVENLABS_API_KEY environment variable not set.");
+  console.error("Set it with: export ELEVENLABS_API_KEY=your_key_here");
+  process.exit(1);
+}
+
+function apiRequest(
+  path: string,
+  apiKey: string,
+  method = "GET",
+  data: Record<string, unknown> | null = null,
+): Promise<Buffer> {
+  return new Promise((resolve, reject) => {
+    const headers: Record<string, string> = { "xi-api-key": apiKey };
+    if (data) headers["Content-Type"] = "application/json";
+
+    const req = https.request(
+      { hostname: API_BASE, path: `/v1${path}`, method, headers },
+      (res) => {
+        const chunks: Buffer[] = [];
+        res.on("data", (chunk: Buffer) => chunks.push(chunk));
+        res.on("end", () => {
+          const body = Buffer.concat(chunks);
+          if (res.statusCode && res.statusCode >= 400) {
+            reject(
+              new Error(`API error ${res.statusCode}: ${body.toString()}`),
+            );
+            return;
+          }
+          resolve(body);
+        });
+      },
+    );
+    req.on("error", reject);
+    if (data) req.write(JSON.stringify(data));
+    req.end();
+  });
+}
+
+async function listVoices(apiKey: string) {
+  const body = await apiRequest("/voices", apiKey);
+  const data = JSON.parse(body.toString());
+  console.log("Name".padEnd(30) + "Voice ID".padEnd(30) + "Category");
+  console.log("-".repeat(80));
+  for (const voice of data.voices ?? []) {
+    console.log(
+      (voice.name ?? "").padEnd(30) +
+        (voice.voice_id ?? "").padEnd(30) +
+        (voice.category ?? ""),
+    );
+  }
+}
+
+async function resolveVoice(
+  voiceName: string,
+  apiKey: string,
+): Promise<string> {
+  const body = await apiRequest("/voices", apiKey);
+  const data = JSON.parse(body.toString());
+  for (const voice of data.voices ?? []) {
+    if ((voice.name ?? "").toLowerCase() === voiceName.toLowerCase()) {
+      return voice.voice_id;
+    }
+  }
+  throw new Error(`Voice '${voiceName}' not found. Use --list-voices to see available voices.`);
+}
+
+async function generateTTS(
+  text: string,
+  voiceId: string,
+  apiKey: string,
+  outputPath: string,
+) {
+  const { dirname: dirName } = await import("path");
+  const audio = await apiRequest(
+    `/text-to-speech/${voiceId}?output_format=${DEFAULT_OUTPUT_FORMAT}`,
+    apiKey,
+    "POST",
+    { text, model_id: DEFAULT_MODEL },
+  );
+  mkdirSync(dirName(outputPath), { recursive: true });
+  writeFileSync(outputPath, audio);
+}
+
+// ── Core processing function (used by both CLI and API) ─────────────────────
+
+export async function processScript(opts: ProcessScriptOptions): Promise<TtsResult> {
+  const {
+    scriptPath,
+    projectId,
+    featureId,
+    mediaBase,
+    force = false,
+    voiceId: voiceIdOpt,
+    voice,
+    dryRun = false,
+  } = opts;
+
+  const resolvedPath = resolve(scriptPath);
+  if (!existsSync(resolvedPath)) {
+    throw new Error(`Script file not found: ${resolvedPath}`);
+  }
+
+  const mediaDir = mediaBase
+    ? join(mediaBase, featureId)
+    : join("/data/workspaces", projectId, "media", featureId);
+  const audioDir = join(mediaDir, "audio");
+  const videoDir = join(mediaDir, "video");
+  const durationsFile = join(audioDir, "durations.json");
+  const videoDurationsFile = join(mediaDir, "video-durations.json");
+  const hashesFile = join(audioDir, "hashes.json");
+
+  const markdown = readFileSync(resolvedPath, "utf-8");
+  const narrations = parseNarrations(markdown);
+  const screenCaptures = parseScreenCaptures(markdown);
+
+  if (narrations.length === 0) {
+    throw new Error("No :::narration directives found in the script.");
+  }
+
+  // Check for missing video files and measure video durations
+  const videoDurations: Record<string, number> = {};
+  if (screenCaptures.length > 0) {
+    for (const c of screenCaptures) {
+      const videoPath = join(videoDir, `${c.id}.mp4`);
+      if (!existsSync(videoPath)) continue;
+      const dur = getMp4Duration(videoPath);
+      if (dur !== null) {
+        videoDurations[c.id] = dur;
+      }
+    }
+  }
+
+  mkdirSync(audioDir, { recursive: true });
+
+  const savedHashes = loadHashes(hashesFile);
+  const newHashes: Record<string, string> = {};
+  const errors: string[] = [];
+
+  const toGenerate: Narration[] = [];
+  let skipped = 0;
+  for (const n of narrations) {
+    const audioPath = join(audioDir, `${n.id}.mp3`);
+    const exists = existsSync(audioPath);
+    const currentHash = hashText(n.text);
+    newHashes[n.id] = currentHash;
+    const hashChanged = savedHashes[n.id] !== currentHash;
+
+    if (!exists || force || hashChanged) {
+      toGenerate.push(n);
+    } else {
+      skipped++;
+    }
+  }
+
+  let generated = 0;
+  if (toGenerate.length > 0 && !dryRun) {
+    const apiKey = process.env.ELEVENLABS_API_KEY;
+    if (!apiKey) {
+      throw new Error("ELEVENLABS_API_KEY environment variable not set.");
+    }
+
+    let finalVoiceId = DEFAULT_VOICE_ID;
+    if (voiceIdOpt) {
+      finalVoiceId = voiceIdOpt;
+    } else if (voice) {
+      finalVoiceId = await resolveVoice(voice, apiKey);
+    }
+
+    for (const n of toGenerate) {
+      const audioPath = join(audioDir, `${n.id}.mp3`);
+      try {
+        await generateTTS(n.text, finalVoiceId, apiKey, audioPath);
+        generated++;
+      } catch (err) {
+        errors.push(`${n.id}: ${(err as Error).message}`);
+      }
+    }
+  }
+
+  // Save text hashes
+  writeFileSync(hashesFile, JSON.stringify(newHashes, null, 2));
+
+  // Compute audio durations
+  const durations: Record<string, number> = {};
+  for (const n of narrations) {
+    const audioPath = join(audioDir, `${n.id}.mp3`);
+    const dur = getAudioDuration(audioPath);
+    if (dur !== null) {
+      durations[n.id] = dur;
+    }
+  }
+
+  writeFileSync(durationsFile, JSON.stringify(durations, null, 2));
+
+  // Write video durations
+  if (Object.keys(videoDurations).length > 0) {
+    writeFileSync(videoDurationsFile, JSON.stringify(videoDurations, null, 2));
+  }
+
+  return {
+    processed: narrations.length,
+    generated,
+    skipped,
+    errors,
+    durations,
+    audioBasePath: audioDir,
+  };
+}
+
+// ── CLI ──────────────────────────────────────────────────────────────────────
+
+function parseArgs(argv: string[]): CliArgs {
+  const args: CliArgs = {
+    script: null,
+    projectId: null,
+    featureId: null,
+    mediaBase: null,
+    force: false,
+    voice: null,
+    voiceId: null,
+    dryRun: false,
+    json: false,
+    listVoices: false,
+    help: false,
+  };
+  let i = 0;
+  while (i < argv.length) {
+    const arg = argv[i];
+    switch (arg) {
+      case "--project-id":
+        args.projectId = argv[++i];
+        break;
+      case "--feature-id":
+        args.featureId = argv[++i];
+        break;
+      case "--media-base":
+        args.mediaBase = argv[++i];
+        break;
+      case "--force":
+        args.force = true;
+        break;
+      case "--voice":
+        args.voice = argv[++i];
+        break;
+      case "--voice-id":
+        args.voiceId = argv[++i];
+        break;
+      case "--dry-run":
+        args.dryRun = true;
+        break;
+      case "--json":
+        args.json = true;
+        break;
+      case "--list-voices":
+        args.listVoices = true;
+        break;
+      case "-h":
+      case "--help":
+        args.help = true;
+        break;
+      default:
+        if (!arg.startsWith("-") && !args.script) {
+          args.script = arg;
+        }
+        break;
+    }
+    i++;
+  }
+  return args;
+}
+
+function printHelp() {
+  console.log(`Usage: tsx scripts/process_script.ts <script.md> --project-id <id> --feature-id <id> [options]
+
+Processes a video script: generates TTS audio, measures audio and video
+durations, checks for missing video files, and writes duration JSON files.
+
+Arguments:
+  script.md              Path to script markdown file
+
+Required:
+  --project-id ID        Project ID (resolves media directory)
+  --feature-id ID        Feature ID (scopes media within project)
+
+Options:
+  --media-base DIR       Override media base dir (default: /data/workspaces/<projectId>/media)
+  --force                Regenerate all audio, even if files exist
+  --voice NAME           ElevenLabs voice name (default: George)
+  --voice-id ID          ElevenLabs voice ID (overrides --voice)
+  --dry-run              Show what would be generated without calling the API
+  --json                 Output machine-readable JSON summary
+  --list-voices          List available ElevenLabs voices
+  -h, --help             Show this help`);
+}
+
+// ── Main ─────────────────────────────────────────────────────────────────────
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (args.help) {
+    printHelp();
+    return;
+  }
+
+  if (args.listVoices) {
+    const apiKey = loadApiKey();
+    await listVoices(apiKey);
+    return;
+  }
+
+  if (!args.script) {
+    console.error("Error: script path is required.");
+    printHelp();
+    process.exit(1);
+  }
+
+  if (!args.projectId || !args.featureId) {
+    console.error("Error: --project-id and --feature-id are required.");
+    process.exit(1);
+  }
+
+  try {
+    const result = await processScript({
+      scriptPath: args.script,
+      projectId: args.projectId,
+      featureId: args.featureId,
+      mediaBase: args.mediaBase ?? undefined,
+      force: args.force,
+      voiceId: args.voiceId ?? undefined,
+      voice: args.voice ?? undefined,
+      dryRun: args.dryRun,
+    });
+
+    if (args.json) {
+      console.log(JSON.stringify(result));
+    } else {
+      console.log(`Processed: ${result.processed} narration(s)`);
+      console.log(`Generated: ${result.generated} audio file(s)`);
+      console.log(`Skipped:   ${result.skipped} (up to date)`);
+      if (result.errors.length > 0) {
+        console.log(`Errors:    ${result.errors.length}`);
+        for (const err of result.errors) {
+          console.log(`  - ${err}`);
+        }
+      }
+      console.log(`\nAudio durations:`);
+      for (const [id, dur] of Object.entries(result.durations)) {
+        console.log(`  ${id}: ${dur.toFixed(2)}s`);
+      }
+      console.log(`\nAudio base path: ${result.audioBasePath}`);
+    }
+  } catch (err) {
+    if (args.json) {
+      console.log(JSON.stringify({ error: (err as Error).message }));
+      process.exit(1);
+    } else {
+      console.error(`Error: ${(err as Error).message}`);
+      process.exit(1);
+    }
+  }
+}
+
+// Only run when executed directly (not when imported for testing)
+const isMainModule =
+  import.meta.url === `file://${process.argv[1]}` ||
+  process.argv[1]?.endsWith("process_script.ts");
+
+if (isMainModule) {
+  main();
+}

package/templates/assistkick-product-system/packages/video/style.css

@@ -0,0 +1 @@
+@import "tailwindcss";

package/templates/assistkick-product-system/packages/video/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "skipLibCheck": true,
+    "lib": ["ESNext", "DOM", "DOM.Iterable"],
+    "jsx": "react-jsx",
+    "jsxImportSource": "react",
+    "resolveJsonModule": true,
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "types": ["react", "react-dom"]
+  },
+  "include": ["./**/*"],
+  "exclude": ["node_modules"]
+}

package/templates/assistkick-product-system/tests/graph_legend.test.ts

@@ -90,7 +90,7 @@ describe('GraphLegend data logic', () => {
       const { NODE_COLORS, EDGE_COLORS, TYPE_LABELS } = await import('../packages/frontend/src/constants/graph.js');
 
       const expectedNodeTypes = [
-        'feature', 'component', 'data_entity', 'decision', 'tech_choice',
+        'feature', 'epic', 'component', 'data_entity', 'decision', 'tech_choice',
         'non_functional_requirement', 'design_token', 'design_pattern',
         'user_role', 'flow', 'assumption', 'open_question',
       ];
@@ -180,6 +180,7 @@ describe('GraphLegend data logic', () => {
 
       const expected = {
         feature: 'Feature',
+        epic: 'Epic',
         component: 'Component',
         data_entity: 'Data Entity',
         decision: 'Decision',