@goodtek/vibeops 0.2.0

package/dist/lib/task-pull.js

@@ -0,0 +1,354 @@
+/**
+ * Planning + execution helpers for `vibeops task pull`.
+ *
+ * Notion is queried for TASK rows whose Status matches `--status` (default
+ * "Planned"). For each row that does NOT yet have a local TASK file we plan
+ * a new `docs/tasks/TASK-NNN-slug.md` skeleton.
+ *
+ * Rules:
+ *   - Never overwrite an existing local file.
+ *   - Never write any TASK body section beyond the Notion-sourced metadata.
+ *   - Always include a `## Notion Page` section so `notion sync` can later
+ *     update the same row in place.
+ *
+ * Mutation surface:
+ *   - `executePullEntry` writes the local file and (if Docs Path on Notion
+ *     was empty) optionally updates the Notion page's Docs Path. Callers in
+ *     dry-run mode MUST skip this.
+ */
+import { readdir } from "node:fs/promises";
+import { basename, join, posix } from "node:path";
+import { pathExists, writeText } from "./filesystem.js";
+import { projectPaths } from "./paths.js";
+import { formatTaskId, highestTaskNumber, } from "./task.js";
+import { slugify } from "./task-generator.js";
+import { readRichText, readSelect, readStatus, readTitle, richTextEqualsFilter, richTextProperty, statusEqualsFilter, andFilter, } from "./notion-mappers.js";
+import { renderPulledTaskMarkdown, } from "./task-summary.js";
+export function rowFromNotionPage(page) {
+    const p = page.properties;
+    return {
+        pageId: page.id,
+        taskId: readRichText(p["Task ID"]),
+        name: readTitle(p.Name),
+        status: readStatus(p.Status),
+        mvpPhase: readSelect(p["MVP Phase"]),
+        priority: readSelect(p.Priority),
+        summary: readRichText(p.Summary),
+        docsPath: readRichText(p["Docs Path"]),
+    };
+}
+const DEFAULT_STATUS_NAMES = ["Planned"];
+const DEFAULT_LIMIT = 20;
+const MAX_LIMIT = 100;
+function buildPullFilter(projectId, statusNames) {
+    const statusFilters = statusNames.map((n) => statusEqualsFilter("Status", n));
+    const statusFilter = statusFilters.length === 1
+        ? statusFilters[0]
+        : { or: statusFilters };
+    return andFilter([
+        richTextEqualsFilter("Project ID", projectId),
+        statusFilter,
+    ]);
+}
+/**
+ * Notion `Docs Path` is **trusted only when its basename matches the TASK
+ * ID**. A row whose Task ID is `TASK-099` but whose Docs Path points at
+ * `docs/tasks/TASK-012-package-polish-readme.md` is a mismatch — surfacing
+ * it as `local-file-exists` silently shadows the real TASK-099 candidate.
+ *
+ * Acceptable basenames (case sensitive — Notion is case sensitive here):
+ *   - `TASK-099.md`
+ *   - `TASK-099-anything.md`  (the standard `TASK-NNN-slug.md` form)
+ *
+ * Anything else is a mismatch.
+ */
+export function docsPathMatchesTaskId(docsRelativePath, taskId) {
+    if (docsRelativePath.length === 0 || taskId.length === 0)
+        return false;
+    const base = basename(docsRelativePath);
+    return base === `${taskId}.md` || base.startsWith(`${taskId}-`);
+}
+/** Scan `docs/tasks` for any file whose basename starts with `TASK-NNN`. */
+async function findLocalTaskFileForId(docsTasksDir, taskId) {
+    let entries;
+    try {
+        entries = await readdir(docsTasksDir);
+    }
+    catch {
+        return null;
+    }
+    for (const name of entries) {
+        if (name === `${taskId}.md` || name.startsWith(`${taskId}-`)) {
+            return join(docsTasksDir, name);
+        }
+    }
+    return null;
+}
+export async function planPull(inputs) {
+    const statusNames = inputs.statusNames ?? DEFAULT_STATUS_NAMES;
+    const limit = Math.max(1, Math.min(inputs.limit ?? DEFAULT_LIMIT, MAX_LIMIT));
+    const res = await inputs.client.queryDataSource(inputs.tasksDataSourceId, {
+        filter: buildPullFilter(inputs.projectId, statusNames),
+        pageSize: limit,
+    });
+    const paths = projectPaths(inputs.cwd);
+    const startCounter = await highestTaskNumber(paths.docsTasks);
+    let nextNumber = startCounter + 1;
+    const entries = [];
+    const skipped = [];
+    const trace = [];
+    // First pass: detect duplicate Task IDs across the Notion query result so
+    // a second row with the same id cannot quietly create a second entry. We
+    // keep the first row and skip subsequent ones with `duplicate-task-id`.
+    const seenTaskIds = new Set();
+    const duplicatePageIds = new Set();
+    for (const page of res.results) {
+        const id = rowFromNotionPage(page).taskId.trim();
+        if (id.length === 0)
+            continue;
+        if (seenTaskIds.has(id)) {
+            duplicatePageIds.add(page.id);
+        }
+        else {
+            seenTaskIds.add(id);
+        }
+    }
+    for (const page of res.results) {
+        const row = rowFromNotionPage(page);
+        const notionDocsPath = row.docsPath.trim();
+        // (A) Task ID required — guard against blank ids before we touch local fs.
+        const taskIdRaw = row.taskId.trim();
+        if (taskIdRaw.length === 0 && notionDocsPath.length === 0) {
+            // No Task ID and no Docs Path → allocate a fresh one, treated as a
+            // legitimate "new" candidate (existing behaviour). Trace it so
+            // `--verbose` makes the allocation visible.
+            const taskId = formatTaskId(nextNumber);
+            nextNumber++;
+            const slug = slugify(row.name.length > 0 ? row.name : taskId, taskId.toLowerCase());
+            const docsRelativePath = posix.join("docs/tasks", `${taskId}-${slug}.md`);
+            const absPath = join(paths.docsTasks, `${taskId}-${slug}.md`);
+            // Even an allocated id may already be present on disk (race / manual
+            // creation). Re-check.
+            if (await pathExists(absPath)) {
+                skipped.push({
+                    pageId: page.id,
+                    taskId,
+                    reason: "local-file-exists",
+                    docsRelativePath,
+                    detail: `local resolved path: ${docsRelativePath}`,
+                });
+                trace.push({
+                    taskId,
+                    pageId: page.id,
+                    notionDocsPath,
+                    localResolvedPath: docsRelativePath,
+                    decision: "skip-local-file-exists",
+                    reason: "Task ID was empty, allocated next id already on disk",
+                });
+                continue;
+            }
+            entries.push({
+                pageId: page.id,
+                taskId,
+                title: row.name.length > 0 ? row.name : taskId,
+                status: row.status,
+                mvpPhase: row.mvpPhase,
+                summary: row.summary,
+                docsRelativePath,
+                absPath,
+                notionNeedsDocsPath: true,
+                detail: "allocated Task ID (Notion row had none)",
+            });
+            trace.push({
+                taskId,
+                pageId: page.id,
+                notionDocsPath: "",
+                localResolvedPath: docsRelativePath,
+                decision: "new-file",
+                reason: "Task ID empty → allocated; no local file with that id",
+            });
+            continue;
+        }
+        if (taskIdRaw.length === 0) {
+            // Has a Docs Path but no Task ID — refuse to act. Renaming pages from
+            // empty ids is risky and not in TASK-011 scope.
+            skipped.push({
+                pageId: page.id,
+                taskId: "(none)",
+                reason: "no-task-id",
+                docsRelativePath: notionDocsPath,
+                detail: `notion docs path: ${notionDocsPath}`,
+            });
+            trace.push({
+                taskId: "(none)",
+                pageId: page.id,
+                notionDocsPath,
+                localResolvedPath: notionDocsPath,
+                decision: "skip-no-task-id",
+                reason: "Notion row has Docs Path but no Task ID",
+            });
+            continue;
+        }
+        const taskId = taskIdRaw;
+        // (A.2) duplicate Task ID across the considered rows.
+        if (duplicatePageIds.has(page.id)) {
+            skipped.push({
+                pageId: page.id,
+                taskId,
+                reason: "duplicate-task-id",
+                docsRelativePath: notionDocsPath,
+                detail: `another Notion row already used this Task ID in the same query`,
+            });
+            trace.push({
+                taskId,
+                pageId: page.id,
+                notionDocsPath,
+                localResolvedPath: "",
+                decision: "skip-duplicate-task-id",
+                reason: "duplicate Task ID across considered rows — kept first row only",
+            });
+            continue;
+        }
+        // (B) Notion Docs Path exists but does NOT match this Task ID. Refuse
+        // to create / overwrite — surface a `docs-path-mismatch` so the user
+        // can fix Notion. We deliberately do NOT auto-rename — auto-fixing
+        // Notion's Docs Path on a mismatch is reserved for a future
+        // `--fix-docs-path` opt-in.
+        if (notionDocsPath.length > 0 &&
+            !docsPathMatchesTaskId(notionDocsPath, taskId)) {
+            skipped.push({
+                pageId: page.id,
+                taskId,
+                reason: "docs-path-mismatch",
+                docsRelativePath: notionDocsPath,
+                detail: `notion docs path: ${notionDocsPath}\n` +
+                    `expected basename prefix: ${taskId}- or ${taskId}.md\n` +
+                    `action: fix Notion 'Docs Path' for this row (auto-fix not enabled).`,
+            });
+            trace.push({
+                taskId,
+                pageId: page.id,
+                notionDocsPath,
+                localResolvedPath: notionDocsPath,
+                decision: "skip-docs-path-mismatch",
+                reason: `Notion Docs Path basename does not match ${taskId}- prefix`,
+            });
+            continue;
+        }
+        // (C) / (D) / (F) — resolve where the local file would live and check
+        // for existing files. If Notion gave us a matching Docs Path, honour
+        // it. Otherwise scan `docs/tasks` for any `TASK-NNN-*.md` already on
+        // disk; if found, treat the row as `local-file-exists`. If not, plan a
+        // new `TASK-NNN-slug.md`.
+        const slug = slugify(row.name.length > 0 ? row.name : taskId, taskId.toLowerCase());
+        let docsRelativePath;
+        let absPath;
+        let notionNeedsDocsPath;
+        let decisionDetail;
+        if (notionDocsPath.length > 0) {
+            docsRelativePath = notionDocsPath;
+            absPath = join(inputs.cwd, notionDocsPath);
+            notionNeedsDocsPath = false;
+            decisionDetail = `notion docs path: ${notionDocsPath}`;
+        }
+        else {
+            const existing = await findLocalTaskFileForId(paths.docsTasks, taskId);
+            if (existing !== null) {
+                const rel = posix.join("docs/tasks", basename(existing));
+                skipped.push({
+                    pageId: page.id,
+                    taskId,
+                    reason: "local-file-exists",
+                    docsRelativePath: rel,
+                    detail: `local resolved path: ${rel}\n` +
+                        `notion docs path: (empty)`,
+                });
+                trace.push({
+                    taskId,
+                    pageId: page.id,
+                    notionDocsPath: "",
+                    localResolvedPath: rel,
+                    decision: "skip-local-file-exists",
+                    reason: "Notion Docs Path empty, but a local file matching the Task ID was found on disk",
+                });
+                continue;
+            }
+            docsRelativePath = posix.join("docs/tasks", `${taskId}-${slug}.md`);
+            absPath = join(paths.docsTasks, `${taskId}-${slug}.md`);
+            notionNeedsDocsPath = true;
+            decisionDetail = `local resolved path: ${docsRelativePath}`;
+        }
+        if (await pathExists(absPath)) {
+            skipped.push({
+                pageId: page.id,
+                taskId,
+                reason: "local-file-exists",
+                docsRelativePath,
+                detail: decisionDetail,
+            });
+            trace.push({
+                taskId,
+                pageId: page.id,
+                notionDocsPath,
+                localResolvedPath: docsRelativePath,
+                decision: "skip-local-file-exists",
+                reason: notionDocsPath.length > 0
+                    ? "Notion Docs Path matched Task ID and file already exists on disk"
+                    : "local search found a file matching the Task ID",
+            });
+            continue;
+        }
+        entries.push({
+            pageId: page.id,
+            taskId,
+            title: row.name.length > 0 ? row.name : taskId,
+            status: row.status,
+            mvpPhase: row.mvpPhase,
+            summary: row.summary,
+            docsRelativePath,
+            absPath,
+            notionNeedsDocsPath,
+            detail: decisionDetail,
+        });
+        trace.push({
+            taskId,
+            pageId: page.id,
+            notionDocsPath,
+            localResolvedPath: docsRelativePath,
+            decision: "new-file",
+            reason: notionDocsPath.length > 0
+                ? "Notion Docs Path matched Task ID — local file does not exist yet"
+                : "Notion Docs Path empty — planning fresh local file under docs/tasks",
+        });
+    }
+    return { entries, skipped, considered: res.results.length, trace };
+}
+export async function executePullEntry(client, entry) {
+    const md = renderPulledTaskMarkdown({
+        taskId: entry.taskId,
+        title: entry.title,
+        status: entry.status,
+        mvpPhase: entry.mvpPhase,
+        summary: entry.summary,
+        pageId: entry.pageId,
+        docsRelativePath: entry.docsRelativePath,
+    });
+    await writeText(entry.absPath, md);
+    let notionUpdated = false;
+    if (entry.notionNeedsDocsPath) {
+        await client.updatePage({
+            pageId: entry.pageId,
+            properties: {
+                "Docs Path": richTextProperty(entry.docsRelativePath),
+            },
+        });
+        notionUpdated = true;
+    }
+    return {
+        taskId: entry.taskId,
+        pageId: entry.pageId,
+        absPath: entry.absPath,
+        docsRelativePath: entry.docsRelativePath,
+        notionUpdated,
+    };
+}

package/dist/lib/task-scaffold.js

@@ -0,0 +1,128 @@
+import { basename, join } from "node:path";
+import { pathExists, writeText } from "./filesystem.js";
+import { formatTaskId, highestTaskNumber } from "./task.js";
+import { slugify } from "./task-generator.js";
+export async function planScaffoldEntries(inputs) {
+    const startNumber = (await highestTaskNumber(inputs.tasksDir)) + 1;
+    const baseSlug = slugify(inputs.slug ?? "planned-task", "planned-task");
+    const baseTitle = inputs.title ?? "(scaffolded TASK — fill in)";
+    const phase = inputs.phase ?? "(unassigned)";
+    const entries = [];
+    let cursor = startNumber;
+    for (let i = 0; i < inputs.count; i++) {
+        // skip numbers whose file already exists on disk so users running scaffold
+        // twice in a row don't collide with previously generated skeletons.
+        let candidatePath = "";
+        let chosen = -1;
+        while (chosen < 0) {
+            const fileName = `${formatTaskId(cursor)}-${baseSlug}.md`;
+            const abs = join(inputs.tasksDir, fileName);
+            if (!(await pathExists(abs))) {
+                chosen = cursor;
+                candidatePath = abs;
+            }
+            cursor++;
+        }
+        entries.push({
+            id: formatTaskId(chosen),
+            number: chosen,
+            slug: baseSlug,
+            title: baseTitle,
+            fileName: basename(candidatePath),
+            absPath: candidatePath,
+            phase,
+        });
+    }
+    return { entries, startNumber };
+}
+export function renderScaffoldMarkdown(entry) {
+    return `# ${entry.id} · ${entry.title}
+
+> This file is a skeleton produced by \`vibeops task generate --scaffold\`. \`vibeops task done\` will refuse to advance the task until every section is filled in.
+
+## Status
+
+planned
+
+## MVP Phase
+
+${entry.phase}
+
+## Goal
+
+(scaffold — describe in 2-4 sentences what becomes possible when this TASK ships.)
+
+## Background
+
+(scaffold — why now, which earlier TASKs or decisions this builds on.)
+
+## Scope
+
+- (scaffold — item 1)
+- (scaffold — item 2)
+
+## Out of Scope
+
+- (scaffold — items intentionally excluded)
+
+## Acceptance Criteria
+
+1. (scaffold — verifiable statement 1)
+2. (scaffold — verifiable statement 2)
+
+## Files to Inspect First
+
+- (scaffold)
+
+## Expected Files to Change
+
+- new: (scaffold)
+- update: (scaffold)
+
+## Risks
+
+- (scaffold)
+
+## Test Plan
+
+- (scaffold)
+
+## Rollback Plan
+
+- (scaffold — branch deletion or another recovery flow)
+
+## Git Context
+
+(populated by \`vibeops task start ${entry.id}\`)
+
+## Notion Page
+
+(populated by \`vibeops notion sync\`)
+
+## Implementation Plan
+
+1. (scaffold)
+
+## Result
+
+(not yet)
+
+## Test Result
+
+(not yet)
+
+## Review Notes
+
+(not yet)
+`;
+}
+export async function writeScaffoldFiles(plan) {
+    const written = [];
+    for (const entry of plan.entries) {
+        if (await pathExists(entry.absPath))
+            continue;
+        await writeText(entry.absPath, renderScaffoldMarkdown(entry));
+        written.push(entry.absPath);
+    }
+    return written;
+}