@goodtek/vibeops 0.2.0

package/dist/lib/notion-sync.js

@@ -0,0 +1,337 @@
+/**
+ * Planning + execution helpers for `vibeops notion sync`.
+ *
+ * Layers:
+ *   1. `loadSyncContext` — read everything we need (config, token, schema,
+ *      project docs, tasks). Pure I/O. No Notion calls.
+ *   2. `buildProjectRow` / `buildTaskRow` — pure synchronous mappers from
+ *      local data → Notion property objects. Easy to unit-test.
+ *   3. `planProjectSync` / `planTaskSync` — given a context + an *existing*
+ *      Notion DB schema, decide what to push. Returns a plan that includes
+ *      the Notion property object so the caller can either dry-print or hand
+ *      it to `executeSync*` for the real API call.
+ *   4. `findExistingProject` / `findExistingTask` — query Notion to discover
+ *      whether the upsert target already exists. These are the only
+ *      network-bound helpers in this file.
+ *   5. `executeProjectUpsert` / `executeTaskUpsert` — perform the actual
+ *      `pages.create` or `pages.update` call.
+ *
+ * Notion API mutation lives behind `executeProjectUpsert` /
+ * `executeTaskUpsert` only — callers passing `dryRun: true` MUST skip both.
+ */
+import { relative } from "node:path";
+import { gitRemoteUrl } from "./git.js";
+import { PROJECTS_DB_PROPERTIES, TASKS_DB_PROPERTIES, validateDatabaseSchema, } from "./notion-schema.js";
+import { resolveNotionDataSourceTarget, } from "./notion-target.js";
+import { andFilter, gitRepoProperty, mapTaskStatusToNotion, readRichText, readStatus, readTitle, richTextEqualsFilter, richTextProperty, selectProperty, statusProperty, titleProperty, } from "./notion-mappers.js";
+import { loadNotionEnv } from "./notion-env.js";
+import { notionProjectsTargetId, notionTasksTargetId, readConfig, } from "./config.js";
+import { readTextOrNull } from "./filesystem.js";
+import { projectPaths } from "./paths.js";
+import { join } from "node:path";
+import { readGitContext, scanTasks } from "./task.js";
+import { detectCurrentPhase, summarizeGoal, summarizeMarkdownLead, summarizeResult, } from "./task-summary.js";
+import { createNotionClient, notionApiError, } from "./notion-client.js";
+export async function loadSyncContext(cwd) {
+    const config = await readConfig(cwd);
+    if (config === null) {
+        return {
+            ok: false,
+            reason: "no-config",
+            message: ".vibeops.json not found. Run `vibeops init` first.",
+        };
+    }
+    const notion = config.notion;
+    if (notion === undefined || !notion.enabled) {
+        return {
+            ok: false,
+            reason: "notion-not-enabled",
+            message: "Notion integration is disabled. Enable it with `vibeops notion init --enable` and set the DB ids.",
+        };
+    }
+    if (notionProjectsTargetId(notion).length === 0) {
+        return {
+            ok: false,
+            reason: "no-projects-db",
+            message: "`.vibeops.json` `notion.projectsTargetId` or `notion.projectsDatabaseId` is empty. Fill it in with `vibeops notion init`.",
+        };
+    }
+    if (notionTasksTargetId(notion).length === 0) {
+        return {
+            ok: false,
+            reason: "no-tasks-db",
+            message: "`.vibeops.json` `notion.tasksTargetId` or `notion.tasksDatabaseId` is empty. Fill it in with `vibeops notion init`.",
+        };
+    }
+    const env = await loadNotionEnv(cwd);
+    if (env.token === null) {
+        return {
+            ok: false,
+            reason: "no-token",
+            message: "`NOTION_TOKEN` not found. Set it in `.vibeops.env` or as an environment variable (NOTION_TOKEN=secret_...).",
+        };
+    }
+    const paths = projectPaths(cwd);
+    const overviewPath = join(paths.docsProject, "00-overview.md");
+    const overviewRaw = (await readTextOrNull(overviewPath)) ?? "";
+    const overviewSummary = summarizeMarkdownLead(overviewRaw);
+    // `docs/project/05-current-state.md` is the canonical name; the VibeOps
+    // repo itself still uses the legacy `03-current-state.md` filename. Honour both.
+    let currentStateRaw = (await readTextOrNull(join(paths.docsProject, "05-current-state.md"))) ?? "";
+    if (currentStateRaw.length === 0) {
+        currentStateRaw =
+            (await readTextOrNull(join(paths.docsProject, "03-current-state.md"))) ?? "";
+    }
+    const currentPhase = detectCurrentPhase(currentStateRaw) || "MVP";
+    const gitRepoUrl = (await gitRemoteUrl(cwd, "origin")) ?? "";
+    const tasks = await scanTasks(paths.docsTasks);
+    return {
+        ok: true,
+        cwd,
+        notion,
+        token: env.token,
+        tokenSource: env.source,
+        project: {
+            config,
+            projectId: config.name,
+            projectName: config.name,
+            cwd,
+            docsProjectPath: relative(cwd, paths.docsProject) || "docs/project",
+            overviewSummary,
+            currentPhase,
+            gitRepoUrl,
+        },
+        tasks,
+    };
+}
+/**
+ * Convert a `ResolveResult` into a {@link SchemaReport}.
+ *
+ * Always returns — `ok: false` paths surface as a `missing-properties`
+ * violation so callers can render a meaningful diagnostic without crashing.
+ */
+function reportFromResolved(required, db, resolved, fallbackId) {
+    if (!resolved.ok) {
+        return {
+            inputObject: resolved.partial?.inputObject ?? "(unknown)",
+            resolvedObject: "(unresolved)",
+            inputId: fallbackId,
+            resolvedId: "",
+            source: "input-data-source",
+            properties: {},
+            propertiesMissing: true,
+            violations: [
+                {
+                    db,
+                    property: "(properties)",
+                    kind: "missing-properties",
+                    allowedTypes: [],
+                    description: resolved.message,
+                },
+            ],
+            gitRepoType: "",
+            warnings: [],
+        };
+    }
+    const violations = validateDatabaseSchema({
+        db,
+        required,
+        retrieveResponse: resolved.properties,
+    });
+    const gitRepoProp = resolved.properties["Git Repo"];
+    const gitRepoType = gitRepoProp?.type === "url" || gitRepoProp?.type === "rich_text"
+        ? gitRepoProp.type
+        : "";
+    return {
+        inputObject: resolved.inputObject,
+        resolvedObject: resolved.resolvedObject,
+        inputId: resolved.inputId,
+        resolvedId: resolved.resolvedId,
+        source: resolved.source,
+        ...(resolved.title !== undefined ? { title: resolved.title } : {}),
+        ...(resolved.parentDatabaseId !== undefined
+            ? { parentDatabaseId: resolved.parentDatabaseId }
+            : {}),
+        properties: resolved.properties,
+        propertiesMissing: false,
+        violations,
+        gitRepoType,
+        warnings: resolved.warnings,
+    };
+}
+export async function fetchSchemas(client, notion) {
+    let projectsResolved;
+    try {
+        projectsResolved = await resolveNotionDataSourceTarget(client, notionProjectsTargetId(notion), "projects");
+    }
+    catch (err) {
+        return { ok: false, reason: "projects-retrieve", error: notionApiError(err) };
+    }
+    let tasksResolved;
+    try {
+        tasksResolved = await resolveNotionDataSourceTarget(client, notionTasksTargetId(notion), "tasks");
+    }
+    catch (err) {
+        return { ok: false, reason: "tasks-retrieve", error: notionApiError(err) };
+    }
+    // All structured resolver failures (transport / no-data-source /
+    // no-properties) funnel through `reportFromResolved` so the CLI can show
+    // its rich `${kind} DB target` block + the resolver's actionable hint.
+    // We only fast-fail on resolver-side exceptions (caught above).
+    return {
+        ok: true,
+        projects: reportFromResolved(PROJECTS_DB_PROPERTIES, "projects", projectsResolved, notionProjectsTargetId(notion)),
+        tasks: reportFromResolved(TASKS_DB_PROPERTIES, "tasks", tasksResolved, notionTasksTargetId(notion)),
+    };
+}
+// ─── property builders ────────────────────────────────────────────────────
+export function buildProjectProperties(project, gitRepoType) {
+    return {
+        Name: titleProperty(project.projectName),
+        "Project ID": richTextProperty(project.projectId),
+        Status: statusProperty("Building"),
+        "Local Path": richTextProperty(project.cwd),
+        "Git Repo": gitRepoProperty(project.gitRepoUrl, gitRepoType === "url" ? "url" : "rich_text"),
+        "Current Phase": selectProperty(project.currentPhase),
+        "Docs Path": richTextProperty(project.docsProjectPath),
+        Summary: richTextProperty(project.overviewSummary),
+    };
+}
+export async function buildTaskRow(task, ctx) {
+    const body = (await readTextOrNull(task.filePath)) ?? "";
+    const goal = summarizeGoal(body);
+    const result = summarizeResult(body);
+    const gitContext = await readGitContext(task.filePath).catch(() => null);
+    const gitBranch = gitContext?.taskBranch ?? "";
+    const docsRelativePath = relative(ctx.cwd, task.filePath) || task.filePath;
+    const properties = {
+        Name: titleProperty(task.title.length > 0 ? task.title : task.id),
+        "Task ID": richTextProperty(task.id),
+        "Project ID": richTextProperty(ctx.project.projectId),
+        Status: statusProperty(mapTaskStatusToNotion(task.status)),
+        Priority: selectProperty(task.priority ?? "P2"),
+        "MVP Phase": selectProperty(task.mvpPhase ?? ""),
+        "Git Branch": richTextProperty(gitBranch),
+        "Docs Path": richTextProperty(docsRelativePath),
+        Summary: richTextProperty(goal),
+        "Result Summary": richTextProperty(result),
+    };
+    return {
+        taskId: task.id,
+        title: task.title,
+        docsRelativePath,
+        properties,
+    };
+}
+export async function findExistingProject(client, dataSourceId, projectId) {
+    const res = await client.queryDataSource(dataSourceId, {
+        filter: richTextEqualsFilter("Project ID", projectId),
+        pageSize: 1,
+    });
+    const page = res.results[0];
+    return page ? { id: page.id, properties: page.properties } : null;
+}
+export async function findExistingTask(client, dataSourceId, projectId, taskId) {
+    const res = await client.queryDataSource(dataSourceId, {
+        filter: andFilter([
+            richTextEqualsFilter("Task ID", taskId),
+            richTextEqualsFilter("Project ID", projectId),
+        ]),
+        pageSize: 1,
+    });
+    const page = res.results[0];
+    return page ? { id: page.id, properties: page.properties } : null;
+}
+/**
+ * Task IDs that VibeOps never pushes to Notion. `TASK-000-template.md` is a
+ * scaffolding template that lives in `docs/tasks/` only so `task generate`
+ * has a stable copy to clone — Notion should not show it as a real TASK row.
+ */
+export const SYNC_EXCLUDED_TASK_IDS = new Set(["TASK-000"]);
+export async function planSync(inputs) {
+    const { ctx, schemas, detectExisting, client } = inputs;
+    const plan = {
+        project: null,
+        tasks: [],
+        counts: {
+            project: { create: 0, update: 0 },
+            tasks: { create: 0, update: 0 },
+        },
+    };
+    if (inputs.onlyTasks !== true) {
+        const props = buildProjectProperties(ctx.project, schemas.projects.gitRepoType);
+        let existing = null;
+        if (detectExisting) {
+            existing = await findExistingProject(client, schemas.projects.resolvedId, ctx.project.projectId);
+        }
+        const verb = existing ? "update" : "create";
+        plan.project = {
+            verb,
+            existingPageId: existing?.id ?? null,
+            properties: props,
+        };
+        plan.counts.project[verb]++;
+    }
+    if (inputs.onlyProject !== true) {
+        for (const task of ctx.tasks) {
+            if (SYNC_EXCLUDED_TASK_IDS.has(task.id))
+                continue;
+            const row = await buildTaskRow(task, ctx);
+            let existing = null;
+            if (detectExisting) {
+                existing = await findExistingTask(client, schemas.tasks.resolvedId, ctx.project.projectId, task.id);
+            }
+            const verb = existing ? "update" : "create";
+            plan.tasks.push({
+                taskId: task.id,
+                title: row.title,
+                docsRelativePath: row.docsRelativePath,
+                verb,
+                existingPageId: existing?.id ?? null,
+                properties: row.properties,
+            });
+            plan.counts.tasks[verb]++;
+        }
+    }
+    return plan;
+}
+export async function executeProjectUpsert(client, dataSourceId, entry) {
+    if (entry.verb === "update" && entry.existingPageId !== null) {
+        const res = await client.updatePage({
+            pageId: entry.existingPageId,
+            properties: entry.properties,
+        });
+        return { verb: "update", pageId: res.id };
+    }
+    const res = await client.createPageInDataSource({
+        dataSourceId,
+        properties: entry.properties,
+    });
+    return { verb: "create", pageId: res.id };
+}
+export async function executeTaskUpsert(client, dataSourceId, entry) {
+    if (entry.verb === "update" && entry.existingPageId !== null) {
+        const res = await client.updatePage({
+            pageId: entry.existingPageId,
+            properties: entry.properties,
+        });
+        return { verb: "update", pageId: res.id, taskId: entry.taskId };
+    }
+    const res = await client.createPageInDataSource({
+        dataSourceId,
+        properties: entry.properties,
+    });
+    return { verb: "create", pageId: res.id, taskId: entry.taskId };
+}
+// ─── helpers for command output ───────────────────────────────────────────
+export function readExistingProjectIdentity(page) {
+    return {
+        name: readTitle(page.properties.Name),
+        projectId: readRichText(page.properties["Project ID"]),
+    };
+}
+export function readExistingTaskStatus(page) {
+    return readStatus(page.properties.Status);
+}
+// re-export so commands don't need a second import
+export { createNotionClient };

package/dist/lib/notion-target.js

@@ -0,0 +1,247 @@
+/**
+ * Resolve a user-stored Notion id (saved in `.vibeops.json` as a "database
+ * id") to the underlying `data_source` that actually carries the property
+ * schema.
+ *
+ * Why this exists
+ * ───────────────
+ * In the current Notion API ("2025-09-03" and later) a `database` object is a
+ * shell that owns 0…N `data_source` children. The real schema (`properties`)
+ * lives on the `data_source`. `databases.retrieve(id).properties` is
+ * deprecated and frequently comes back `undefined` on workspaces that have
+ * been migrated. Result: VibeOps' `notion test` / `notion sync` saw
+ * `object=database`, no `properties`, and emitted `missing-properties`
+ * violations even though the user's DB schema is fine.
+ *
+ * What this does
+ * ──────────────
+ * `resolveNotionDataSourceTarget(client, id, label)`:
+ *
+ *   A. Try `dataSources.retrieve(id)` first.
+ *      - If the SDK supports it AND the response has a `properties` map → done.
+ *      - If the SDK supports it but Notion responds 4xx, fall through.
+ *      - If the SDK does **not** expose `client.dataSources` (null return),
+ *        fall through.
+ *   B. Try `databases.retrieve(id)`.
+ *      - If the response has `data_sources[]` non-empty, pick `[0]` (warn if
+ *        the array has more than one), then call `dataSources.retrieve` on
+ *        that id.
+ *      - If the response carries a legacy `properties` map (very old SDKs),
+ *        treat the database id itself as the resolved target.
+ *      - If `data_sources` is empty and there is no legacy `properties` map,
+ *        return a structured `missing-properties` error pointing the user
+ *        at the "share the data source with the integration" fix.
+ *   C. Any unexpected exception is normalised through `notionApiError` so
+ *      callers never get a raw SDK Error / TypeError.
+ *
+ * Read-only. No mutation. Never logs the token. Returns `{ ok: true | false,
+ * … }` — no exceptions for the documented failure modes.
+ */
+import { extractDataSourcesFromDatabaseResponse, notionApiError, } from "./notion-client.js";
+import { getNotionProperties, readNotionObjectKind, } from "./notion-schema.js";
+async function tryDataSourcesRetrieve(client, id) {
+    try {
+        const res = await client.dataSourcesRetrieve(id);
+        if (res === null) {
+            return { ok: false, sdkMissing: true };
+        }
+        return { ok: true, response: res };
+    }
+    catch (err) {
+        return { ok: false, apiError: notionApiError(err) };
+    }
+}
+async function tryDatabasesRetrieve(client, id) {
+    try {
+        const res = (await client.databasesRetrieve(id));
+        return { ok: true, response: res };
+    }
+    catch (err) {
+        return { ok: false, apiError: notionApiError(err) };
+    }
+}
+function readTitleText(raw) {
+    if (!Array.isArray(raw))
+        return undefined;
+    const text = raw
+        .map((seg) => seg.plain_text ?? "")
+        .join("")
+        .trim();
+    return text.length > 0 ? text : undefined;
+}
+/**
+ * Common tail for resolver error messages — points the user at the new
+ * `--debug-shape` diagnostic when they need to inspect what Notion actually
+ * returned.
+ */
+const HINT_DEBUG_SHAPE = "Run `vibeops notion test --debug-shape` to inspect the Notion response shape.";
+const HINT_NO_DATA_SOURCE = "Notion returned no data_sources for this database. The integration may " +
+    "be connected to the parent page only — open the database as a full page " +
+    "in Notion and add the VibeOps integration directly via its " +
+    "'⋯ → Connections' menu. " +
+    HINT_DEBUG_SHAPE;
+const HINT_NO_PROPERTIES = "Resolved a data_source but it returned no `properties` map. " +
+    "This usually means the integration has access to the database shell " +
+    "but not the underlying data_source. Open the data source and add the " +
+    "VibeOps integration to it. " +
+    HINT_DEBUG_SHAPE;
+/**
+ * Main entry point.
+ *
+ * Steps A → B → fail, as documented at the top of this file. `label` is
+ * `"projects"` / `"tasks"` etc. and is only used for diagnostic strings.
+ */
+export async function resolveNotionDataSourceTarget(client, id, label) {
+    const warnings = [];
+    // ── A. Try dataSources.retrieve(id) directly ─────────────────────────
+    const dsOutcome = await tryDataSourcesRetrieve(client, id);
+    if (dsOutcome.ok && dsOutcome.response) {
+        const ds = dsOutcome.response;
+        const props = getNotionProperties(ds);
+        if (props !== null) {
+            return {
+                ok: true,
+                inputId: id,
+                resolvedId: typeof ds.id === "string" && ds.id.length > 0 ? ds.id : id,
+                label,
+                inputObject: readNotionObjectKind(ds),
+                resolvedObject: "data_source",
+                source: "input-data-source",
+                ...(readTitleText(ds.title) !== undefined
+                    ? { title: readTitleText(ds.title) }
+                    : {}),
+                ...(typeof ds.parent?.database_id === "string"
+                    ? { parentDatabaseId: ds.parent.database_id }
+                    : {}),
+                properties: props,
+                warnings,
+            };
+        }
+        warnings.push(`dataSources.retrieve(${id}) succeeded but returned no properties map.`);
+    }
+    else if (dsOutcome.apiError !== undefined &&
+        dsOutcome.apiError.code !== "object_not_found" &&
+        dsOutcome.apiError.code !== "validation_error" &&
+        dsOutcome.apiError.code !== "unknown_error") {
+        // unauthorized / restricted_resource / rate_limited / timeout — surface
+        // these immediately rather than masquerading as a missing data source.
+        return {
+            ok: false,
+            inputId: id,
+            label,
+            reason: "transport",
+            message: dsOutcome.apiError.message,
+            apiError: dsOutcome.apiError,
+        };
+    }
+    else if (dsOutcome.apiError !== undefined &&
+        dsOutcome.apiError.code === "object_not_found") {
+        warnings.push(`dataSources.retrieve(${id}) → object_not_found (id is likely a database id, falling back).`);
+    }
+    // (sdkMissing or 4xx that we want to fall through)
+    // ── B. Try databases.retrieve(id) ────────────────────────────────────
+    const dbOutcome = await tryDatabasesRetrieve(client, id);
+    if (!dbOutcome.ok || dbOutcome.response === undefined) {
+        const apiErr = dbOutcome.apiError ?? {
+            ok: false,
+            code: "unknown_error",
+            message: "databases.retrieve failed without a structured error.",
+        };
+        return {
+            ok: false,
+            inputId: id,
+            label,
+            reason: "transport",
+            message: apiErr.message,
+            apiError: apiErr,
+        };
+    }
+    const db = dbOutcome.response;
+    const inputObject = readNotionObjectKind(db);
+    const dbProps = getNotionProperties(db);
+    const dbTitle = readTitleText(db.title);
+    const dbId = typeof db.id === "string" && (db.id).length > 0
+        ? (db.id)
+        : id;
+    // Centralised parser handles `data_sources` / `dataSources` /
+    // `child_data_sources` / `childDataSources` + nested `data_source.id`.
+    const extracted = extractDataSourcesFromDatabaseResponse(db);
+    if (extracted.field !== null && extracted.field !== "data_sources") {
+        warnings.push(`database response carried data sources under '${extracted.field}' (non-canonical naming).`);
+    }
+    const childIds = extracted.items.map((it) => it.id);
+    // ── Legacy SDK / very old workspace: properties on database itself ───
+    if (dbProps !== null && childIds.length === 0) {
+        warnings.push("Legacy database object carries a `properties` map directly — using it (no data_source fallback needed).");
+        return {
+            ok: true,
+            inputId: id,
+            resolvedId: dbId,
+            label,
+            inputObject,
+            resolvedObject: "database",
+            source: "legacy-database",
+            ...(dbTitle !== undefined ? { title: dbTitle } : {}),
+            properties: dbProps,
+            warnings,
+        };
+    }
+    if (childIds.length === 0) {
+        return {
+            ok: false,
+            inputId: id,
+            label,
+            reason: "no-data-source",
+            message: HINT_NO_DATA_SOURCE,
+            partial: { inputObject, childDataSourceIds: [] },
+        };
+    }
+    if (childIds.length > 1) {
+        warnings.push(`database has ${childIds.length} data_sources — used [0]; ids: ${childIds.join(", ")}.`);
+    }
+    const chosenId = childIds[0];
+    const childOutcome = await tryDataSourcesRetrieve(client, chosenId);
+    if (!childOutcome.ok || childOutcome.response === undefined || childOutcome.response === null) {
+        const apiErr = childOutcome.apiError ?? {
+            ok: false,
+            code: "unknown_error",
+            message: `dataSources.retrieve(${chosenId}) failed without a structured error.`,
+        };
+        return {
+            ok: false,
+            inputId: id,
+            label,
+            reason: "transport",
+            message: apiErr.message,
+            apiError: apiErr,
+            partial: { inputObject, childDataSourceIds: childIds },
+        };
+    }
+    const child = childOutcome.response;
+    const childProps = getNotionProperties(child);
+    if (childProps === null) {
+        return {
+            ok: false,
+            inputId: id,
+            label,
+            reason: "no-properties",
+            message: `Resolved data_source ${chosenId} returned no properties map. ${HINT_NO_PROPERTIES}`,
+            partial: { inputObject, childDataSourceIds: childIds },
+        };
+    }
+    return {
+        ok: true,
+        inputId: id,
+        resolvedId: typeof child.id === "string" && child.id.length > 0 ? child.id : chosenId,
+        label,
+        inputObject,
+        resolvedObject: "data_source",
+        source: "database-default-data-source",
+        ...(readTitleText(child.title) !== undefined
+            ? { title: readTitleText(child.title) }
+            : {}),
+        parentDatabaseId: dbId,
+        properties: childProps,
+        warnings,
+    };
+}