@goodtek/vibeops 0.2.0

package/dist/lib/notion-env.js

@@ -0,0 +1,140 @@
+import { join } from "node:path";
+import { pathExists, readTextOrNull, writeText } from "./filesystem.js";
+import { VIBEOPS_ENV_FILE } from "./paths.js";
+/**
+ * Minimal `.env` parser — handles the subset we need:
+ *   - blank lines and `#` comments are ignored
+ *   - `KEY=value` (optional whitespace around `=`)
+ *   - surrounding single or double quotes are stripped
+ *   - inline `#` comments after `value ` are stripped (but only when the value
+ *     itself is not quoted)
+ *
+ * We intentionally don't depend on `dotenv` to keep the install footprint
+ * small and to avoid surprising behaviours (e.g. silent override of
+ * `process.env`).
+ */
+export function parseDotenv(text) {
+    const out = {};
+    for (const rawLine of text.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (line.length === 0 || line.startsWith("#"))
+            continue;
+        const eq = line.indexOf("=");
+        if (eq <= 0)
+            continue;
+        const key = line.slice(0, eq).trim();
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key))
+            continue;
+        let val = line.slice(eq + 1).trim();
+        const quoted = (val.startsWith('"') && val.endsWith('"')) ||
+            (val.startsWith("'") && val.endsWith("'"));
+        if (quoted) {
+            val = val.slice(1, -1);
+        }
+        else {
+            const hash = val.indexOf(" #");
+            if (hash !== -1)
+                val = val.slice(0, hash).trim();
+        }
+        out[key] = val;
+    }
+    return out;
+}
+/**
+ * Resolve the Notion API token. Priority:
+ *   1. `.vibeops.env` in the project root (preferred — not committed)
+ *   2. `process.env.NOTION_TOKEN`
+ *
+ * Returns the raw token. Callers MUST mask before printing.
+ */
+export async function loadNotionEnv(cwd) {
+    const envPath = join(cwd, VIBEOPS_ENV_FILE);
+    const text = await readTextOrNull(envPath);
+    if (text !== null) {
+        const parsed = parseDotenv(text);
+        const fromFile = parsed.NOTION_TOKEN ?? "";
+        if (fromFile.length > 0) {
+            return { token: fromFile, source: ".vibeops.env" };
+        }
+    }
+    const fromProcess = process.env.NOTION_TOKEN ?? "";
+    if (fromProcess.length > 0) {
+        return { token: fromProcess, source: "process.env" };
+    }
+    return { token: null, source: "none" };
+}
+/**
+ * Token-source probe for `vibeops status` and similar read-only flows.
+ *
+ * Returns only whether a token is reachable and where it came from. The token
+ * VALUE never leaves this function — callers cannot accidentally leak it via
+ * logs.
+ */
+export async function getNotionTokenSource(cwd) {
+    const env = await loadNotionEnv(cwd);
+    return { hasToken: env.token !== null, source: env.source };
+}
+/**
+ * Mask a secret for safe display. Keeps the first 4 and last 4 characters so
+ * the user can sanity-check which token is loaded without revealing the body.
+ */
+export function maskToken(value) {
+    if (value.length <= 8)
+        return "*".repeat(value.length);
+    return `${value.slice(0, 4)}…${value.slice(-4)} (len=${value.length})`;
+}
+export async function inspectEnvFile(cwd) {
+    const path = join(cwd, VIBEOPS_ENV_FILE);
+    const raw = await readTextOrNull(path);
+    if (raw === null)
+        return { exists: false, raw: null, currentToken: null };
+    const parsed = parseDotenv(raw);
+    const value = typeof parsed.NOTION_TOKEN === "string" ? parsed.NOTION_TOKEN : null;
+    return { exists: true, raw, currentToken: value };
+}
+const DEFAULT_ENV_HEADER = `# VibeOps · local environment (DO NOT COMMIT)
+# This file is .gitignored. Holds the Notion integration secret VibeOps reads.
+`;
+/**
+ * Write or update the \`NOTION_TOKEN=...\` line inside the project's
+ * \`.vibeops.env\`.
+ *
+ * Rules:
+ *   - We never echo the token value anywhere — caller is responsible for
+ *     keeping it out of logs.
+ *   - If the file doesn't exist, we create it with a header (no other keys).
+ *   - If the file exists, we preserve every other line. We replace the first
+ *     \`NOTION_TOKEN=...\` line we find, or append one to the end otherwise.
+ */
+export async function writeNotionTokenToEnvFile(cwd, token) {
+    const path = join(cwd, VIBEOPS_ENV_FILE);
+    const exists = await pathExists(path);
+    const line = `NOTION_TOKEN=${token}`;
+    if (!exists) {
+        await writeText(path, `${DEFAULT_ENV_HEADER}\n${line}\n`);
+        return { path, created: true, replaced: false };
+    }
+    const raw = (await readTextOrNull(path)) ?? "";
+    const lines = raw.split(/\r?\n/);
+    let replaced = false;
+    for (let i = 0; i < lines.length; i++) {
+        const trimmed = lines[i].trimStart();
+        if (trimmed.startsWith("NOTION_TOKEN=") || trimmed.startsWith("NOTION_TOKEN =")) {
+            lines[i] = line;
+            replaced = true;
+            break;
+        }
+    }
+    let next;
+    if (replaced) {
+        next = lines.join("\n");
+        if (!next.endsWith("\n"))
+            next += "\n";
+    }
+    else {
+        const trailing = raw.endsWith("\n") ? "" : "\n";
+        next = `${raw}${trailing}${line}\n`;
+    }
+    await writeText(path, next);
+    return { path, created: false, replaced };
+}

package/dist/lib/notion-mappers.js

@@ -0,0 +1,148 @@
+/**
+ * Pure mappers between VibeOps local data (TASK markdown / project docs /
+ * config) and Notion API property objects.
+ *
+ * Side-effect free: every function in this file is a synchronous data
+ * transformation that the caller can unit-test or dry-run without ever
+ * touching the network.
+ *
+ * Property names match `PROJECTS_DB_PROPERTIES` / `TASKS_DB_PROPERTIES` in
+ * `notion-schema.ts` exactly (case-sensitive).
+ */
+import { statusDisplay } from "./task.js";
+/**
+ * Notion `rich_text` and most string-like properties hard-limit a single
+ * text run at 2000 characters. We pick a smaller 1500-char ceiling so we
+ * don't bump into multi-byte edge cases or implicit 0-pad on the way back.
+ */
+export const NOTION_TEXT_LIMIT = 1500;
+export function truncate(text, limit = NOTION_TEXT_LIMIT) {
+    if (text.length <= limit)
+        return text;
+    return `${text.slice(0, limit - 1)}…`;
+}
+// ─── property builders ────────────────────────────────────────────────────
+export function titleProperty(text) {
+    return {
+        title: [{ type: "text", text: { content: truncate(text || "(untitled)") } }],
+    };
+}
+export function richTextProperty(text) {
+    if (text.length === 0) {
+        return { rich_text: [] };
+    }
+    return {
+        rich_text: [{ type: "text", text: { content: truncate(text) } }],
+    };
+}
+export function urlProperty(text) {
+    return { url: text.length > 0 ? text : null };
+}
+export function selectProperty(name) {
+    if (name.length === 0)
+        return { select: null };
+    return { select: { name: truncate(name, 100) } };
+}
+export function statusProperty(name) {
+    if (name.length === 0)
+        return { status: null };
+    return { status: { name: truncate(name, 100) } };
+}
+/**
+ * Build a property for "Git Repo" — a value the user's Notion DB might have
+ * declared as either `rich_text` *or* `url`. The caller passes the type it
+ * actually saw from `databases.retrieve()`.
+ */
+export function gitRepoProperty(url, propertyType) {
+    if (propertyType === "url")
+        return urlProperty(url);
+    return richTextProperty(url);
+}
+// ─── status mapping (TASK markdown ↔ Notion) ──────────────────────────────
+const TASK_TO_NOTION = {
+    planned: "Planned",
+    in_progress: "In Progress",
+    review: "Review",
+    blocked: "Blocked",
+    done: "Done",
+};
+const NOTION_NAME_TO_TASK = {
+    planned: "planned",
+    ready: "planned",
+    todo: "planned",
+    "in progress": "in_progress",
+    in_progress: "in_progress",
+    doing: "in_progress",
+    review: "review",
+    "in review": "review",
+    blocked: "blocked",
+    done: "done",
+    closed: "done",
+};
+export function mapTaskStatusToNotion(status) {
+    return TASK_TO_NOTION[status] ?? "Planned";
+}
+export function mapNotionStatusNameToTask(notionName) {
+    const key = notionName.trim().toLowerCase();
+    return NOTION_NAME_TO_TASK[key] ?? "planned";
+}
+export function taskStatusDisplay(status) {
+    return statusDisplay(status);
+}
+// ─── readers (Notion API response → string) ───────────────────────────────
+export function readTitle(prop) {
+    const arr = prop?.title;
+    if (!Array.isArray(arr) || arr.length === 0)
+        return "";
+    return arr
+        .map((seg) => seg.plain_text ?? "")
+        .join("")
+        .trim();
+}
+export function readRichText(prop) {
+    const arr = prop?.rich_text;
+    if (!Array.isArray(arr) || arr.length === 0)
+        return "";
+    return arr
+        .map((seg) => seg.plain_text ?? "")
+        .join("")
+        .trim();
+}
+export function readUrl(prop) {
+    const v = prop?.url;
+    return typeof v === "string" ? v : "";
+}
+export function readSelect(prop) {
+    const v = prop?.select?.name;
+    return typeof v === "string" ? v : "";
+}
+export function readStatus(prop) {
+    const v = prop?.status?.name;
+    return typeof v === "string" ? v : "";
+}
+/**
+ * Read either `rich_text` or `url` and return whichever has content. Useful
+ * for the "Git Repo" property which the user may have declared as either type.
+ */
+export function readUrlOrRichText(prop) {
+    const url = readUrl(prop);
+    if (url.length > 0)
+        return url;
+    return readRichText(prop);
+}
+// ─── filter builders ──────────────────────────────────────────────────────
+export function richTextEqualsFilter(propertyName, value) {
+    return {
+        property: propertyName,
+        rich_text: { equals: value },
+    };
+}
+export function statusEqualsFilter(propertyName, value) {
+    return {
+        property: propertyName,
+        status: { equals: value },
+    };
+}
+export function andFilter(filters) {
+    return { and: [...filters] };
+}

package/dist/lib/notion-schema.js

@@ -0,0 +1,272 @@
+/**
+ * Required Notion property schema for the **Projects DB** and **Tasks DB**.
+ *
+ * VibeOps validates the shape with `databases.retrieve` (read-only). It
+ * never tries to create or migrate the schema — humans manage Notion.
+ *
+ * Property names are matched case-sensitively, exactly as users see them in
+ * the Notion UI. If your Notion property has a different name or type, your
+ * `notion test` will fail with a clear error.
+ */
+/**
+ * Status option names VibeOps writes to the Projects DB. Add/rename these in
+ * Notion (`Status` property → `Edit options`). Anything missing causes a
+ * pre-flight `status-options-missing` violation; nothing is auto-created.
+ */
+export const PROJECTS_STATUS_REQUIRED_OPTIONS = [
+    "Building",
+    "Planning",
+    "Paused",
+    "Done",
+    "Archived",
+];
+/**
+ * Status option names VibeOps writes to the Tasks DB. Mirrors the TASK
+ * lifecycle (`Planned → In Progress → Review → Done`) plus `Blocked`.
+ */
+export const TASKS_STATUS_REQUIRED_OPTIONS = [
+    "Planned",
+    "In Progress",
+    "Review",
+    "Done",
+    "Blocked",
+];
+export const PROJECTS_DB_PROPERTIES = [
+    { name: "Name", allowedTypes: ["title"], description: "Project page title (Notion 'Title' column)" },
+    { name: "Project ID", allowedTypes: ["rich_text"], description: "Matches .vibeops.json projectId" },
+    { name: "Status", allowedTypes: ["status"], description: "Project status (Notion 'Status' type; not select)", requiredOptions: PROJECTS_STATUS_REQUIRED_OPTIONS },
+    { name: "Local Path", allowedTypes: ["rich_text"], description: "Local repository path" },
+    { name: "Git Repo", allowedTypes: ["rich_text", "url"], description: "Remote repository URL (rich_text or url allowed)" },
+    { name: "Current Phase", allowedTypes: ["select"], description: "Current phase label" },
+    { name: "Docs Path", allowedTypes: ["rich_text"], description: "docs/project path" },
+    { name: "Summary", allowedTypes: ["rich_text"], description: "Summary of 00-overview.md" },
+];
+export const TASKS_DB_PROPERTIES = [
+    { name: "Name", allowedTypes: ["title"], description: "TASK page title" },
+    { name: "Task ID", allowedTypes: ["rich_text"], description: "TASK-NNN" },
+    { name: "Project ID", allowedTypes: ["rich_text"], description: "Owning project id" },
+    { name: "Status", allowedTypes: ["status"], description: "Planned / In Progress / Review / Done / Blocked (Notion 'Status' type)", requiredOptions: TASKS_STATUS_REQUIRED_OPTIONS },
+    { name: "Priority", allowedTypes: ["select"], description: "P0 / P1 / P2 / …" },
+    { name: "MVP Phase", allowedTypes: ["select"], description: "Phase label (free-form select; compatibility name)" },
+    { name: "Git Branch", allowedTypes: ["rich_text"], description: "task/TASK-NNN-slug" },
+    { name: "Docs Path", allowedTypes: ["rich_text"], description: "docs/tasks/TASK-NNN-*.md" },
+    { name: "Summary", allowedTypes: ["rich_text"], description: "TASK Goal summary" },
+    { name: "Result Summary", allowedTypes: ["rich_text"], description: "TASK Result summary (set on Review/Done)" },
+];
+/**
+ * Friendly prefix shown in CLI output / 4xx hints whenever a status option
+ * is missing. Surface it verbatim so user knows it's a Notion-side action.
+ */
+export const STATUS_OPTIONS_HINT = "Add missing Status options to the Notion database, then rerun `vibeops notion test`.";
+/**
+ * Friendly bilingual hint reused by `notion test` and `notion sync` when the
+ * retrieve response does not expose a `properties` object. Surface it
+ * verbatim in CLI error output — it is referenced from TASK-011 docs.
+ */
+export const MISSING_PROPERTIES_HINT = "Could not read Notion database properties. " +
+    "This may happen if the selected ID is not a database/data source ID, " +
+    "or the integration does not have access to the database itself. " +
+    "Open the database as a full page and share it with the VibeOps integration, " +
+    "then run `vibeops notion test`.";
+/**
+ * Best-effort extraction of a Notion `properties` map from a value that may be:
+ *   - `undefined` / `null` / non-object → `null`
+ *   - a `databases.retrieve()` response  →  the nested `properties` object
+ *   - a `data_source` retrieve response  →  the nested `properties` object
+ *   - a bare `properties` map already    →  the value itself
+ *
+ * VibeOps schema validators must funnel every input through this helper so
+ * a malformed response (legacy SDK, partial mock, wrong id) yields a clean
+ * `missing-properties` violation instead of a `TypeError`.
+ */
+export function getNotionProperties(input) {
+    if (input === null || input === undefined || typeof input !== "object") {
+        return null;
+    }
+    const obj = input;
+    const props = obj.properties;
+    if (props !== undefined && props !== null && typeof props === "object") {
+        return props;
+    }
+    // Already a properties map? Look for at least one well-known VibeOps key.
+    if ("Name" in obj ||
+        "Task ID" in obj ||
+        "Project ID" in obj ||
+        "Status" in obj) {
+        return obj;
+    }
+    return null;
+}
+/**
+ * Best-effort extraction of the Notion API object kind:
+ *   - `databases.retrieve()`   → "database"
+ *   - data_source retrieve     → "data_source"
+ *   - anything else / missing  → "(unknown)"
+ *
+ * Used by callers to render diagnostic detail without leaking any token.
+ */
+export function readNotionObjectKind(input) {
+    if (input === null || input === undefined || typeof input !== "object") {
+        return "(unknown)";
+    }
+    const obj = input;
+    return typeof obj.object === "string" ? obj.object : "(unknown)";
+}
+export function validateDatabaseSchema(inputs) {
+    const properties = getNotionProperties(inputs.retrieveResponse);
+    if (properties === null) {
+        return [
+            {
+                db: inputs.db,
+                property: "(properties)",
+                kind: "missing-properties",
+                allowedTypes: [],
+                description: MISSING_PROPERTIES_HINT,
+            },
+        ];
+    }
+    const violations = [];
+    for (const req of inputs.required) {
+        const prop = properties[req.name];
+        if (prop === undefined || prop === null) {
+            violations.push({
+                db: inputs.db,
+                property: req.name,
+                kind: "missing",
+                allowedTypes: req.allowedTypes,
+                description: req.description,
+            });
+            continue;
+        }
+        const actual = typeof prop.type === "string"
+            ? prop.type
+            : "(unknown)";
+        if (!req.allowedTypes.includes(actual)) {
+            violations.push({
+                db: inputs.db,
+                property: req.name,
+                kind: "type-mismatch",
+                actualType: actual,
+                allowedTypes: req.allowedTypes,
+                description: req.description,
+            });
+            // skip option check — type is wrong already
+            continue;
+        }
+        // status options check — only if (a) the requirement has them, (b) the
+        // observed type is `status` (we don't check select/multi_select yet —
+        // VibeOps doesn't write to them at runtime in this MVP).
+        if (req.requiredOptions !== undefined &&
+            req.requiredOptions.length > 0 &&
+            actual === "status") {
+            const extracted = extractStatusOptionNames(prop);
+            if (extracted === null) {
+                violations.push({
+                    db: inputs.db,
+                    property: req.name,
+                    kind: "status-options-unreadable",
+                    allowedTypes: req.allowedTypes,
+                    description: req.description,
+                    requiredOptions: req.requiredOptions,
+                });
+                continue;
+            }
+            const found = new Set(extracted);
+            const missing = req.requiredOptions.filter((n) => !found.has(n));
+            if (missing.length > 0) {
+                violations.push({
+                    db: inputs.db,
+                    property: req.name,
+                    kind: "status-options-missing",
+                    allowedTypes: req.allowedTypes,
+                    description: req.description,
+                    requiredOptions: req.requiredOptions,
+                    missingOptions: missing,
+                    foundOptions: extracted,
+                });
+            }
+        }
+    }
+    return violations;
+}
+/**
+ * Extract `name` strings from a Notion `status` property's `options` array.
+ * Notion's status response shape (API `2025-09-03`) looks like:
+ *
+ *   {
+ *     id: "...",
+ *     name: "Status",
+ *     type: "status",
+ *     status: {
+ *       options: [{ id, name, color, description, ... }, …],
+ *       groups:  [{ id, name, color, option_ids: [...] }, …]
+ *     }
+ *   }
+ *
+ * We also defensively look at `groups[].option_names` (some response shapes)
+ * and the top-level `options` / `status_options` fallbacks. Returns `null`
+ * when the property is shaped in a way we cannot recognise — callers should
+ * surface that as `status-options-unreadable` so the user knows VibeOps
+ * could not pre-flight check the option set rather than silently passing.
+ *
+ * IMPORTANT: never throws.
+ */
+export function extractStatusOptionNames(prop) {
+    if (prop === null || prop === undefined || typeof prop !== "object") {
+        return null;
+    }
+    const names = [];
+    const seen = new Set();
+    const pushName = (raw) => {
+        if (typeof raw !== "string")
+            return;
+        const trimmed = raw.trim();
+        if (trimmed.length === 0)
+            return;
+        if (seen.has(trimmed))
+            return;
+        seen.add(trimmed);
+        names.push(trimmed);
+    };
+    const collectFromOptions = (arr) => {
+        if (!Array.isArray(arr))
+            return;
+        for (const item of arr) {
+            if (item === null || typeof item !== "object")
+                continue;
+            pushName(item.name);
+        }
+    };
+    const obj = prop;
+    // (a) modern shape: prop.status.options[].name
+    const statusBody = obj.status;
+    if (statusBody !== null && typeof statusBody === "object") {
+        const sb = statusBody;
+        collectFromOptions(sb.options);
+        // some response shapes carry `groups[].options[].name` directly.
+        if (Array.isArray(sb.groups)) {
+            for (const g of sb.groups) {
+                if (g !== null && typeof g === "object") {
+                    collectFromOptions(g.options);
+                    const optionNames = g.option_names;
+                    if (Array.isArray(optionNames)) {
+                        for (const n of optionNames)
+                            pushName(n);
+                    }
+                }
+            }
+        }
+    }
+    // (b) flat fallback: prop.options[].name  (older / partial shapes)
+    collectFromOptions(obj.options);
+    // (c) some legacy responses spell it `status_options`.
+    collectFromOptions(obj.status_options);
+    if (names.length === 0) {
+        // Distinguish "we found the property but couldn't read any option names"
+        // from "we read 0 options" — both look the same here, so return null to
+        // tell the caller to surface `status-options-unreadable`. A real Notion
+        // workspace always has at least 1 status option.
+        return null;
+    }
+    return names;
+}