@shanvit7/poiesis 0.1.0

package/src/onboarding.ts

@@ -0,0 +1,57 @@
+/**
+ * First-run onboarding.
+ *
+ * "Sure!" → inject scan prompt → return immediately (false)
+ *           LLM scans + calls poiesis_save_profile
+ *           poiesis_save_profile queues '/poiesis' as followUp
+ *           '/poiesis' fires in fresh context → needsOnboarding=false → runProject
+ *
+ * "No"    → inject QnA prompt → return immediately (false)
+ *           same chain: LLM chats → poiesis_save_profile → followUp → runProject
+ */
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent"
+import { exists } from "./utils.ts"
+
+export const PROFILE_PATH = "~/.poiesis/user-profile.json"
+
+export const needsOnboarding = (): boolean => !exists(PROFILE_PATH)
+
+export const runOnboarding = async (
+  pi: ExtensionAPI,
+  ctx: ExtensionCommandContext
+): Promise<void> => {
+  const pick = await ctx.ui.select(
+    "Mind if I sneak a peek at your GitHub repos and local folders? I won't read any code.",
+    ["Sure!", "No, ask me instead"]
+  )
+
+  if (pick === "Sure!") {
+    await pi.sendUserMessage(
+      `Run \`gh repo list --limit 50 --json name,primaryLanguage,description,updatedAt\` and list directory names (not contents) in ~/Desktop, ~/projects, ~/dev, ~/code.
+
+From what you find, call \`poiesis_save_profile\` with:
+- primaryStack: top languages/frameworks across all repos
+- recentProjects: up to 8 projects, each with:
+    name: repo or dir name
+    summary: one sentence — what was built and what tech was used (use description field or infer from name/language)
+    stack: languages/frameworks in that project
+- recentActivity: one-line summary of what they’ve been building lately
+
+Call the tool immediately once you have enough data. No summary, no greeting. After calling the tool, tell the user to run /poiesis.`
+    )
+    return
+  }
+
+  // Multi-turn QnA path — same tail: LLM calls poiesis_save_profile → followUp → runProject
+  await pi.sendUserMessage(
+    `Ask the user about themselves — one question at a time, casual tone. Find out:
+- primaryStack: languages/frameworks they build with most
+- recentProjects: up to 5 things they've built recently, for each:
+    name: project or repo name
+    summary: one sentence — what they built and what tech they used
+    stack: the main languages/frameworks in that project
+- recentActivity: one-line summary of what they've been working on
+
+Once you have enough, call \`poiesis_save_profile\`. No sign-off after saving.`
+  )
+}

package/src/progress.ts

@@ -0,0 +1,94 @@
+import { join } from "node:path"
+import type { ChapterKind, ChapterMeta, Progress } from "./types.ts"
+import { expandHome, readJson, writeJson } from "./utils.ts"
+
+// ponytail: progress lives in .poiesis/chapters/.progress.json
+const progressPath = (projectDir: string): string =>
+  join(expandHome(projectDir), ".poiesis", "chapters", ".progress.json")
+
+export const readProgress = (projectDir: string): Progress =>
+  readJson<Progress>(progressPath(projectDir))
+
+export const writeProgress = (projectDir: string, p: Progress): void =>
+  writeJson(progressPath(projectDir), p)
+
+/** Create initial .progress.json at scaffold time. */
+export const initProgress = (
+  projectDir: string,
+  total: number,
+  chapters: Record<string, ChapterMeta>
+): void => {
+  const now = new Date().toISOString()
+  writeProgress(projectDir, {
+    current: 1,
+    total,
+    completed: [],
+    startedAt: now,
+    lastActiveAt: now,
+    chapters,
+  })
+}
+
+/** Called by poiesis_run_tests on success. */
+export const markTestsPass = (projectDir: string, chapter: number): void => {
+  const p = readProgress(projectDir)
+  const ch = p.chapters[chapter]
+  if (ch) ch.testsPass = true
+  p.lastActiveAt = new Date().toISOString()
+  writeProgress(projectDir, p)
+}
+
+/** Set chapter type + testsFile after classification. */
+export const setChapterMeta = (
+  projectDir: string,
+  chapter: number,
+  kind: ChapterKind,
+  testsFile: string | null
+): void => {
+  const p = readProgress(projectDir)
+  p.chapters[chapter] = { type: kind, testsFile, testsPass: kind === "theory" ? null : false }
+  p.lastActiveAt = new Date().toISOString()
+  writeProgress(projectDir, p)
+}
+
+/** Move current → next after chapter_done gate passes. */
+export const advanceChapter = (projectDir: string): void => {
+  const p = readProgress(projectDir)
+  if (!p.completed.includes(p.current)) p.completed.push(p.current)
+  p.current = Math.min(p.current + 1, p.total)
+  p.lastActiveAt = new Date().toISOString()
+  writeProgress(projectDir, p)
+}
+
+// ponytail: self-check
+if (process.argv[1]?.endsWith("progress.ts")) {
+  import("node:os").then(({ tmpdir }) => {
+    import("node:fs").then(({ mkdirSync, rmSync }) => {
+      const dir = join(tmpdir(), `poiesis-test-${Date.now()}`)
+      mkdirSync(join(dir, ".poiesis", "chapters"), { recursive: true })
+
+      initProgress(dir, 3, {
+        "1": { type: "code", testsFile: "tests/chapter-1.test.ts", testsPass: false },
+        "2": { type: "theory", testsFile: null, testsPass: null },
+        "3": { type: "code", testsFile: "tests/chapter-3.test.ts", testsPass: false },
+      })
+
+      let p = readProgress(dir)
+      console.assert(p.current === 1, "current should be 1")
+      console.assert(p.total === 3, "total should be 3")
+      console.assert(p.completed.length === 0, "none completed")
+
+      markTestsPass(dir, 1)
+      p = readProgress(dir)
+      console.assert(p.chapters["1"]?.testsPass === true, "chapter 1 should pass")
+
+      advanceChapter(dir)
+      p = readProgress(dir)
+      console.assert(p.current === 2, "current should advance to 2")
+      console.assert(p.completed.includes(1), "chapter 1 should be completed")
+
+      rmSync(dir, { recursive: true })
+      console.log("progress.ts: ok")
+    })
+  })
+}

package/src/project.ts

@@ -0,0 +1,311 @@
+import { mkdirSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent"
+import { initProgress } from "./progress.ts"
+import type { ChapterMeta } from "./types.ts"
+
+/**
+ * Post-onboarding project flow.
+ *
+ * 1. ctx.ui.input — YouTube URL
+ * 2. ctx.ui.input — project name (defaults to YT video title)
+ * 3. Scaffold {cwd}/{name}/chapters/
+ * 4. Gemini (JSON mode) → chapter-index.md + summary.md + chapter-N.md per chapter
+ */
+import { Type as GType, GoogleGenAI } from "@google/genai"
+
+// ── Types ─────────────────────────────────────────────────────────────────────
+
+interface Chapter {
+  title: string
+  concepts: string[]
+  duration: string
+  notes: string
+  keyTakeaway: string
+}
+
+interface VideoAnalysis {
+  summary: string
+  techstack: string
+  chapters: Chapter[]
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+const toFolder = (s: string): string =>
+  s
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 50)
+
+const YT_RE = /(?:youtube\.com\/watch\?v=|youtu\.be\/)([\w-]+)/
+
+const ytTitle = async (url: string): Promise<string> => {
+  try {
+    const res = await fetch(
+      `https://www.youtube.com/oembed?url=${encodeURIComponent(url)}&format=json`
+    )
+    const data = (await res.json()) as { title?: string }
+    return data.title ?? "project"
+  } catch {
+    return "project"
+  }
+}
+
+// ── Gemini analysis ───────────────────────────────────────────────────────────
+
+const analyzeVideo = async (url: string, name: string): Promise<VideoAnalysis> => {
+  const apiKey = process.env.GEMINI_API_KEY
+  if (!apiKey) throw new Error("GEMINI_API_KEY is not set")
+
+  const ai = new GoogleGenAI({ apiKey })
+
+  const result = await ai.models.generateContent({
+    model: "gemini-3.5-flash",
+    contents: [
+      {
+        role: "user",
+        parts: [
+          {
+            text: `Analyze this YouTube tutorial and return structured JSON.
+URL: ${url}
+Project name: "${name}"
+
+Return a JSON object matching the schema exactly. Be specific to the actual video content — no filler.
+
+Fields:
+- summary: 2–3 sentence description of what this project builds and what problem it solves — written as a project README description, not a tutorial summary. Do not mention "this tutorial" or "this video".
+- techstack: a concise Markdown description of the project's tech stack (runtime, package manager, language, framework, key libraries, test runner, any important conventions). This will be injected into every chapter session so the AI tutor never needs to ask. Example: "**Runtime**: Bun\n**Package manager**: bun\n**Language**: TypeScript\n**Framework**: Hono\n**Testing**: Vitest (via bunx)\n\nAll commands use \'bun\'. Strict TypeScript throughout."
+- chapters: array of chapters, each with:
+  - title: short chapter title (no number prefix)
+  - concepts: array of 2–5 key topics covered
+  - duration: estimated time range (e.g. "0:00–8:30")
+  - notes: one sentence on what the viewer builds or learns
+  - keyTakeaway: single most important insight from this chapter`,
+          },
+        ],
+      },
+    ],
+    config: {
+      responseMimeType: "application/json",
+      responseSchema: {
+        type: GType.OBJECT,
+        properties: {
+          summary: { type: GType.STRING },
+          techstack: { type: GType.STRING },
+          chapters: {
+            type: GType.ARRAY,
+            items: {
+              type: GType.OBJECT,
+              properties: {
+                title: { type: GType.STRING },
+                concepts: { type: GType.ARRAY, items: { type: GType.STRING } },
+                duration: { type: GType.STRING },
+                notes: { type: GType.STRING },
+                keyTakeaway: { type: GType.STRING },
+              },
+              required: ["title", "concepts", "duration", "notes", "keyTakeaway"],
+            },
+          },
+        },
+        required: ["summary", "techstack", "chapters"],
+      },
+    },
+  })
+
+  return JSON.parse(result.text ?? "{}") as VideoAnalysis
+}
+
+// ── File builders ─────────────────────────────────────────────────────────────
+
+const buildTechstack = (techstack: string): string => techstack.trim()
+
+const buildRoadmapJson = (name: string, analysis: VideoAnalysis): string =>
+  JSON.stringify(
+    {
+      name,
+      chapters: analysis.chapters.map((ch, i) => ({
+        n: i + 1,
+        title: ch.title,
+        duration: ch.duration,
+        done: false,
+        kind: null,
+      })),
+    },
+    null,
+    2
+  )
+
+const buildSummary = (
+  name: string,
+  url: string,
+  analysis: VideoAnalysis
+): string => `# ${name} — Summary
+
+**Source**: ${url}
+
+${analysis.summary}
+
+## What You'll Learn
+
+${analysis.chapters.map((ch, i) => `- **Chapter ${i + 1}** — ${ch.title}: ${ch.keyTakeaway}`).join("\n")}
+
+---
+
+← [[chapter-index]]
+`
+
+const buildIndex = (name: string, url: string, analysis: VideoAnalysis): string => {
+  const rows = analysis.chapters
+    .map(
+      (ch, i) =>
+        `| [[chapter-${i + 1}\\|Chapter ${i + 1}]] | ${ch.title} | ${ch.duration} | ${ch.concepts.join(", ")} |`
+    )
+    .join("\n")
+
+  return `# ${name} — Chapter Index
+
+**Source**: ${url}
+
+> ${analysis.summary}
+
+[[summary|→ Full Summary]]
+
+## Chapters
+
+| # | Title | Duration | Key Concepts |
+|---|-------|----------|--------------|
+${rows}
+
+---
+
+*${analysis.chapters.length} chapters · generated by poiesis*
+`
+}
+
+const buildChapter = (ch: Chapter, n: number, total: number): string => {
+  const prev = n > 1 ? `[[chapter-${n - 1}|← Chapter ${n - 1}]]` : "[[chapter-index|← Index]]"
+  const next = n < total ? `[[chapter-${n + 1}|Chapter ${n + 1} →]]` : "[[chapter-index|→ Index]]"
+
+  return `# Chapter ${n} — ${ch.title}
+
+**Concepts**: ${ch.concepts.join(", ")}
+**Duration**: ${ch.duration}
+
+## What You Learn
+
+${ch.notes}
+
+## Key Takeaway
+
+> ${ch.keyTakeaway}
+
+---
+
+${prev} · ${next}
+`
+}
+
+// ── Scaffold ──────────────────────────────────────────────────────────────────
+
+const GITIGNORE = `node_modules/
+dist/
+.env
+.env.local
+*.log
+.pi
+.poiesis
+`
+
+const buildReadme = (name: string, url: string, analysis: VideoAnalysis): string =>
+  `# ${name}\n\n${analysis.summary}\n\n---\n\n<sub>Made with help of <a href="https://shanvit7.github.io/poiesis/">Poiesis</a> watching <a href="${url}">${url}</a></sub>\n`
+
+const scaffoldChapters = (
+  chaptersDir: string,
+  projectDir: string,
+  name: string,
+  url: string,
+  analysis: VideoAnalysis
+): void => {
+  const write = (filename: string, content: string): void =>
+    writeFileSync(join(chaptersDir, filename), content, "utf8")
+
+  write("summary.md", buildSummary(name, url, analysis))
+  write("chapter-index.md", buildIndex(name, url, analysis))
+  write("techstack.md", buildTechstack(analysis.techstack))
+  write("roadmap.json", buildRoadmapJson(name, analysis))
+
+  for (let i = 0; i < analysis.chapters.length; i++) {
+    write(
+      `chapter-${i + 1}.md`,
+      buildChapter(analysis.chapters[i], i + 1, analysis.chapters.length)
+    )
+  }
+
+  writeFileSync(join(projectDir, "README.md"), buildReadme(name, url, analysis), "utf8")
+
+  // .gitignore at project root (not inside .poiesis)
+  writeFileSync(join(projectDir, ".gitignore"), GITIGNORE, "utf8")
+
+  // initialise progress — classifyChapter refines type at runtime
+  const chapters: Record<string, ChapterMeta> = {}
+  for (let i = 0; i < analysis.chapters.length; i++) {
+    chapters[i + 1] = { type: "code", testsFile: null, testsPass: false }
+  }
+  initProgress(projectDir, analysis.chapters.length, chapters)
+}
+
+// ── Entry point ───────────────────────────────────────────────────────────────
+
+export const runProject = async (pi: ExtensionAPI, ctx: ExtensionCommandContext): Promise<void> => {
+  // 1. YT URL
+  const url = (await ctx.ui.input("Paste a YouTube URL")) ?? ""
+  if (!YT_RE.test(url)) {
+    ctx.ui.notify("Not a valid YouTube URL — try again.", "error")
+    return
+  }
+
+  // 2. Project name
+  const defaultTitle = await ytTitle(url)
+  const input =
+    (await ctx.ui.input(`Project name — press Enter to use "${defaultTitle}"`, defaultTitle)) ||
+    defaultTitle
+  const name = toFolder(input) || "project"
+
+  // 3. Scaffold directory (.poiesis/chapters lives inside the project)
+  const projectDir = join(ctx.cwd, name)
+  const poiesisChaptersDir = join(projectDir, ".poiesis", "chapters")
+  mkdirSync(poiesisChaptersDir, { recursive: true })
+
+  // 4. Analyze + write files
+  ctx.ui.setStatus("poiesis", " Analyzing video with Gemini…")
+  try {
+    const analysis = await analyzeVideo(url, name)
+    scaffoldChapters(poiesisChaptersDir, projectDir, name, url, analysis)
+    ctx.ui.setStatus("poiesis", undefined)
+
+    // 5. Handoff — trigger the LLM to brief the user on what was created
+    await pi.sendUserMessage(
+      `The poiesis project "${name}" has been scaffolded at: ${projectDir}
+
+What was created:
+- ${analysis.chapters.length} chapter guide files in .poiesis/chapters/
+- techstack.md (tech context injected into every chapter session)
+- roadmap.json, chapter-index.md, summary.md
+- README.md
+- .gitignore
+- .poiesis/chapters/.progress.json (tracks chapter progress)
+
+Tell the user all of the following:
+1. The project is ready at \`${projectDir}\`
+2. How to start: \`cd ${projectDir}\` then run \`/poiesis\`
+3. One-line teaser of chapter 1: "${analysis.chapters[0]?.title ?? "Chapter 1"}"
+
+Be concise — 3–4 sentences max.`
+    )
+  } catch (err) {
+    ctx.ui.setStatus("poiesis", undefined)
+    ctx.ui.notify(`Gemini error: ${String(err)}`, "error")
+  }
+}

package/src/steps.ts

@@ -0,0 +1,66 @@
+/**
+ * Step prompt functions — each loads a .md template from prompts/ and renders {{vars}}.
+ * The .md files are the source of truth; edit them directly to tune prompts.
+ * Consumed by runChapter (on resume) and by gate tools (on advance).
+ */
+
+import { readFileSync } from "fs"
+import { dirname, join } from "path"
+import { fileURLToPath } from "url"
+
+const PROMPTS_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "prompts")
+
+// ponytail: flat {{var}} replace — no handlebars needed for 5 simple templates
+const render = (tmpl: string, vars: Record<string, string>): string =>
+  tmpl.replace(/\{\{(\w+)\}\}/g, (_, k) => vars[k] ?? `{{${k}}}`)
+
+const load = (name: string, vars: Record<string, string> = {}): string =>
+  render(readFileSync(join(PROMPTS_DIR, `${name}.md`), "utf8").trim(), vars)
+
+export const prereqPrompt = (profileContext: string): string => load("prereq", { profileContext })
+
+export const theoryPrompt = (prereqResult: "familiar" | "primed", chapterNum: number): string =>
+  load("theory", { prereqResult, chapterNum: String(chapterNum) })
+
+export const planPrompt = (chapterNum: number): string =>
+  load("plan", { chapterNum: String(chapterNum) })
+
+export const writeTestsPrompt = (testsPlan: Array<{ name: string; why: string }>): string =>
+  load("write-tests", {
+    testsPlan: testsPlan.map((t, i) => `  ${i + 1}. ${t.name} — ${t.why}`).join("\n"),
+  })
+
+export const implementPrompt = (testsFile: string, chapterNum: number): string =>
+  load("implement", { testsFile, chapterNum: String(chapterNum) })
+
+// ponytail: self-check — no LLM, just verify templates load and vars substitute
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const p = prereqPrompt("Stack: TypeScript\n  - hono-api: REST API")
+  console.assert(p.includes("FAMILIAR"), "prereqPrompt missing FAMILIAR path")
+  console.assert(p.includes("UNFAMILIAR"), "prereqPrompt missing UNFAMILIAR path")
+  console.assert(!p.includes("{{"), "prereqPrompt has unresolved vars")
+
+  const t = theoryPrompt("primed", 3)
+  console.assert(t.includes("Prereq result: primed"), "theoryPrompt missing prereqResult")
+  console.assert(t.includes("LIVE RESEARCH RULE"), "theoryPrompt missing live research rule")
+  console.assert(t.includes("poiesis_theory_done"), "theoryPrompt missing gate call")
+  console.assert(!t.includes("{{"), "theoryPrompt has unresolved vars")
+
+  const pl = planPrompt(3)
+  console.assert(pl.includes("chapterNum: 3"), "planPrompt missing chapterNum")
+  console.assert(pl.includes("poiesis_confirm_test_plan"), "planPrompt missing tool call")
+  console.assert(!pl.includes("{{"), "planPrompt has unresolved vars")
+
+  const wt = writeTestsPrompt([{ name: "server 200", why: "proves server starts" }])
+  console.assert(wt.includes("server 200"), "writeTestsPrompt missing test name")
+  console.assert(wt.includes("poiesis_tests_written"), "writeTestsPrompt missing gate call")
+  console.assert(!wt.includes("{{"), "writeTestsPrompt has unresolved vars")
+
+  const imp = implementPrompt("tests/chapter-3.test.ts", 3)
+  console.assert(imp.includes("tests/chapter-3.test.ts"), "implementPrompt missing testsFile")
+  console.assert(imp.includes("chapter=3"), "implementPrompt missing chapterNum in run call")
+  console.assert(imp.includes("CRITICAL RULES"), "implementPrompt missing critical rules")
+  console.assert(!imp.includes("{{"), "implementPrompt has unresolved vars")
+
+  console.log("steps.ts: ok")
+}

package/src/types.ts

@@ -0,0 +1,67 @@
+// ── Chapter / Progress types ──────────────────────────────────────────────
+
+export type ChapterKind = "code" | "theory"
+
+export interface ChapterMeta {
+  type: ChapterKind
+  testsFile: string | null // null = theory chapter
+  testsPass: boolean | null // null = theory; false = failing; true = passing
+}
+
+export interface Progress {
+  current: number
+  total: number
+  completed: number[]
+  startedAt: string
+  lastActiveAt: string
+  chapters: Record<string, ChapterMeta>
+}
+
+// ── User / Config types ─────────────────────────────────────────────────────
+
+export interface RecentProject {
+  name: string // repo or dir name
+  summary: string // one sentence: what was built, key tech used
+  stack: string[] // languages/frameworks in this project
+}
+
+export interface UserProfile {
+  primaryStack: string[] // languages/frameworks used most across all projects
+  recentProjects: RecentProject[] // up to 8 projects with context
+  recentActivity: string // one-line human summary of recent work
+  scannedAt: string // ISO timestamp — stale after 7 days
+}
+
+export interface Config {
+  state_dir: string // ~/.poiesis by default
+  scan_user?: boolean // undefined = not asked yet; true = opted in; false = opted out
+  // ponytail: llm_model / editor_cmd / gemini_api_key removed with tutor/build stripdown
+}
+
+// ── Chapter step state ────────────────────────────────────────────────────────
+
+export type ChapterStep = "prereq" | "theory" | "plan" | "write-tests" | "implement"
+
+export interface ChapterState {
+  step: ChapterStep
+  prereqResult: "familiar" | "primed" | null
+  testsFile: string | null
+  testsPlan: Array<{ name: string; why: string }>
+  testsPass: boolean
+  startedAt: string
+}
+
+// ── Roadmap types ─────────────────────────────────────────────────────────────
+
+export interface RoadmapChapter {
+  n: number
+  title: string
+  duration: string
+  done: boolean
+  kind: ChapterKind | null
+}
+
+export interface Roadmap {
+  name: string
+  chapters: RoadmapChapter[]
+}