@goodtek/vibeops 0.2.0

package/dist/bootstrap/installer.js

@@ -0,0 +1,149 @@
+import { join } from "node:path";
+import { ensureDir, pathExists, readText, readTextOrNull, writeText } from "../lib/filesystem.js";
+import { dim, green, log, yellow } from "../lib/logger.js";
+import { projectPaths, VIBEOPS_ENV_FILE } from "../lib/paths.js";
+import { loadManifest, resolveDestination } from "./manifest.js";
+import { applySubstitutions, buildSubstitutions, isTextPath, } from "./substitute.js";
+import { configToJson } from "../lib/config.js";
+function envExampleContents() {
+    // Modern VibeOps reads exactly one Notion secret: NOTION_TOKEN.
+    // Notion Projects / Tasks target IDs live in `.vibeops.json` under
+    // `notion.projectsTargetId` / `notion.tasksTargetId` (configured by
+    // `vibeops notion init`), so they are NOT environment variables.
+    //
+    // We intentionally do NOT seed GITHUB_TOKEN / OPENAI_* here:
+    //   - GitHub integration uses `gh` CLI auth.
+    //   - VibeOps' default runner is prompt mode and does not call LLM APIs.
+    return [
+        "# VibeOps · environment example",
+        "# Copy this file to .vibeops.env and fill in the value.",
+        "# Never commit .vibeops.env — it is added to .gitignore by `vibeops init`.",
+        "#",
+        "# NOTION_TOKEN is the only secret VibeOps reads. Get it from",
+        "# https://www.notion.so/profile/integrations after creating an internal",
+        "# integration and sharing the target databases with it.",
+        "",
+        "NOTION_TOKEN=",
+        "",
+    ].join("\n");
+}
+async function copyOne(entry, dest, subs, options) {
+    const exists = await pathExists(dest);
+    const relPath = entry.relativePath;
+    if (exists && !options.force) {
+        return { action: "skipped", relativePath: relPath };
+    }
+    if (options.dryRun) {
+        return {
+            action: exists ? "would-overwrite" : "would-create",
+            relativePath: relPath,
+        };
+    }
+    const raw = await readText(entry.sourceAbs);
+    const out = isTextPath(entry.sourceAbs) ? applySubstitutions(raw, subs) : raw;
+    await writeText(dest, out);
+    return {
+        action: exists ? "overwritten" : "created",
+        relativePath: relPath,
+    };
+}
+async function writeBlobIfNeeded(dest, relPath, contents, options) {
+    const exists = await pathExists(dest);
+    if (exists && !options.force) {
+        return { action: "skipped", relativePath: relPath };
+    }
+    if (options.dryRun) {
+        return {
+            action: exists ? "would-overwrite" : "would-create",
+            relativePath: relPath,
+        };
+    }
+    await writeText(dest, contents);
+    return {
+        action: exists ? "overwritten" : "created",
+        relativePath: relPath,
+    };
+}
+async function ensureGitignoreEntry(projectRoot, dryRun) {
+    const path = join(projectRoot, ".gitignore");
+    const existing = await readTextOrNull(path);
+    const line = VIBEOPS_ENV_FILE;
+    if (existing && existing.split("\n").some((l) => l.trim() === line)) {
+        return null;
+    }
+    if (dryRun) {
+        return {
+            action: existing ? "would-overwrite" : "would-create",
+            relativePath: ".gitignore",
+        };
+    }
+    const next = existing
+        ? `${existing.endsWith("\n") ? existing : `${existing}\n`}${line}\n`
+        : `${line}\n`;
+    await writeText(path, next);
+    return {
+        action: existing ? "overwritten" : "created",
+        relativePath: ".gitignore",
+    };
+}
+export async function install(options) {
+    const paths = projectPaths(options.projectRoot);
+    const subs = buildSubstitutions(options.config);
+    if (!options.dryRun) {
+        await ensureDir(paths.root);
+    }
+    const manifest = await loadManifest();
+    const outcomes = [];
+    for (const entry of manifest) {
+        const dest = resolveDestination(entry, paths.root);
+        const outcome = await copyOne(entry, dest, subs, options);
+        outcomes.push(outcome);
+    }
+    const configOutcome = await writeBlobIfNeeded(paths.config, ".vibeops.json", configToJson(options.config), options);
+    outcomes.push(configOutcome);
+    const envExampleOutcome = await writeBlobIfNeeded(paths.envExample, ".vibeops.env.example", envExampleContents(), options);
+    outcomes.push(envExampleOutcome);
+    const gitignoreOutcome = await ensureGitignoreEntry(paths.root, options.dryRun);
+    if (gitignoreOutcome)
+        outcomes.push(gitignoreOutcome);
+    let created = 0;
+    let overwritten = 0;
+    let skipped = 0;
+    for (const o of outcomes) {
+        if (o.action === "created" || o.action === "would-create")
+            created++;
+        else if (o.action === "overwritten" || o.action === "would-overwrite")
+            overwritten++;
+        else
+            skipped++;
+    }
+    return { files: outcomes, created, overwritten, skipped };
+}
+export function printReport(report, dryRun) {
+    for (const f of report.files) {
+        switch (f.action) {
+            case "created":
+                log.ok(`created   ${f.relativePath}`);
+                break;
+            case "overwritten":
+                log.ok(`${yellow("overwrote")} ${f.relativePath}`);
+                break;
+            case "skipped":
+                log.skip(`skipped   ${f.relativePath} (already exists)`);
+                break;
+            case "would-create":
+                log.info(`${dim("would create   ")}${f.relativePath}`);
+                break;
+            case "would-overwrite":
+                log.info(`${dim("would overwrite")} ${f.relativePath}`);
+                break;
+        }
+    }
+    log.blank();
+    if (dryRun) {
+        log.info(`${green("dry-run")}: ${report.created} would be created, ${report.overwritten} would be overwritten, ${report.skipped} already exist.`);
+    }
+    else {
+        log.info(`${green("done")}: ${report.created} created, ${report.overwritten} overwritten, ${report.skipped} skipped.`);
+    }
+}

package/dist/bootstrap/manifest.js

@@ -0,0 +1,15 @@
+import { join, relative } from "node:path";
+import { walk } from "../lib/filesystem.js";
+import { TEMPLATES_ROOT } from "../lib/paths.js";
+export async function loadManifest() {
+    const files = await walk(TEMPLATES_ROOT);
+    return files
+        .map((abs) => ({
+        relativePath: relative(TEMPLATES_ROOT, abs),
+        sourceAbs: abs,
+    }))
+        .sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+}
+export function resolveDestination(entry, projectRoot) {
+    return join(projectRoot, entry.relativePath);
+}

package/dist/bootstrap/substitute.js

@@ -0,0 +1,35 @@
+const TEXT_EXTENSIONS = new Set([
+    ".md",
+    ".mdc",
+    ".txt",
+    ".json",
+    ".yaml",
+    ".yml",
+    ".env",
+    ".example",
+]);
+export function isTextPath(path) {
+    const lower = path.toLowerCase();
+    for (const ext of TEXT_EXTENSIONS) {
+        if (lower.endsWith(ext))
+            return true;
+    }
+    if (lower.endsWith("/readme"))
+        return true;
+    if (lower.endsWith("/agents.md"))
+        return true;
+    return false;
+}
+export function buildSubstitutions(config) {
+    return {
+        PROJECT_NAME: config.name,
+        VIBEOPS_VERSION: config.vibeopsVersion,
+        CREATED_AT: config.createdAt,
+    };
+}
+export function applySubstitutions(content, subs) {
+    return content
+        .replaceAll("{{PROJECT_NAME}}", subs.PROJECT_NAME)
+        .replaceAll("{{VIBEOPS_VERSION}}", subs.VIBEOPS_VERSION)
+        .replaceAll("{{CREATED_AT}}", subs.CREATED_AT);
+}

package/dist/cli.js

@@ -0,0 +1,241 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { agentListCommand } from "./commands/agent-list.js";
+import { agentPromptCommand } from "./commands/agent-prompt.js";
+import { agentShowCommand } from "./commands/agent-show.js";
+import { githubInitCommand } from "./commands/github-init.js";
+import { githubStatusCommand } from "./commands/github-status.js";
+import { initCommand } from "./commands/init.js";
+import { notionInitCommand } from "./commands/notion-init.js";
+import { notionSyncCommand } from "./commands/notion-sync.js";
+import { notionTestCommand } from "./commands/notion-test.js";
+import { planCommand } from "./commands/plan.js";
+import { statusCommand } from "./commands/status.js";
+import { taskCheckCommand } from "./commands/task-check.js";
+import { taskDoneCommand } from "./commands/task-done.js";
+import { taskGenerateCommand } from "./commands/task-generate.js";
+import { taskPullCommand } from "./commands/task-pull.js";
+import { taskRollbackCommand } from "./commands/task-rollback.js";
+import { taskStartCommand } from "./commands/task-start.js";
+import { VERSION } from "./version.js";
+const program = new Command();
+program
+    .name("vibeops")
+    .description("VibeOps — a local CLI that keeps Cursor-based vibe coding on rails.\n" +
+    "  It installs docs, Cursor rules, AGENTS.md, agents, TASK templates,\n" +
+    "  and Git/Notion workflows into a project, then drives work one TASK at a time.")
+    .version(VERSION, "-v, --version", "Print the VibeOps version");
+program
+    .command("init")
+    .description("Install the VibeOps workflow files into the current directory")
+    .option("--dry-run", "Show what would be created without writing any files")
+    .option("--force", "Overwrite existing files (use with care)")
+    .option("--cwd <path>", "Run against a different directory")
+    .option("--name <projectName>", "Project name written into .vibeops.json")
+    .option("--git", "Initialize a Git repository without prompting")
+    .option("--no-git", "Skip Git initialization and commits")
+    .option("--initial-commit", "Run `git add .` and create an initial commit")
+    .option("--no-initial-commit", "Do not create an initial commit")
+    .option("--default-branch <name>", "Default Git branch name (default `main`)")
+    .option("--commit-message <message>", "Initial commit message (default 'chore: initialize vibeops project')")
+    .action(async (options) => {
+    await initCommand(options);
+});
+program
+    .command("status")
+    .description("Show VibeOps installation, TASK counts, and integration state")
+    .option("--json", "Print machine-readable JSON")
+    .option("--cwd <path>", "Inspect a different directory")
+    .action(async (options) => {
+    await statusCommand(options);
+});
+program
+    .command("plan")
+    .description("Run 20 interactive questions and produce a ProjectBrief + Cursor planning prompt")
+    .option("--idea <text>", "One-line idea default (use `Name: idea` to extract the project name)")
+    .option("--from <path>", "Read an existing brief markdown and regenerate the prompt")
+    .option("--output <path>", "Output path for the Cursor planning prompt (default `.vibeops/generated/plan-prompt.md`)")
+    .option("--non-interactive", "Skip prompts and use the supplied values plus safe placeholders")
+    .option("--cwd <path>", "Run against a different directory")
+    .action(async (options) => {
+    await planCommand(options);
+});
+const agent = program
+    .command("agent")
+    .description("Inspect the `.vibeops/agents/*` agent definitions");
+agent
+    .command("list")
+    .description("List available agents")
+    .option("--json", "Print machine-readable JSON")
+    .option("--cwd <path>", "Inspect a different directory")
+    .action(async (options) => {
+    await agentListCommand(options);
+});
+agent
+    .command("show <name>")
+    .description("Print an agent definition body")
+    .option("--raw", "Include frontmatter in the output")
+    .option("--cwd <path>", "Inspect a different directory")
+    .action(async (name, options) => {
+    await agentShowCommand(name, options);
+});
+agent
+    .command("prompt <name> <taskId>")
+    .description("Print a Cursor-ready prompt built from the agent + TASK context")
+    .option("--context <path...>", "Additional context file paths")
+    .option("--cwd <path>", "Inspect a different directory")
+    .action(async (name, taskId, options) => {
+    await agentPromptCommand(name, taskId, options);
+});
+const task = program
+    .command("task")
+    .description("TASK lifecycle commands");
+task
+    .command("generate")
+    .description("Build a Cursor prompt for generating TASK files, or with --scaffold write skeleton TASK markdown")
+    .option("--from <path>", "Primary backlog/brief markdown to feed into the prompt")
+    .option("--output <path>", "Output path for the generated prompt (default `.vibeops/generated/task-generate-prompt.md`)")
+    .option("--count <number>", "Suggested TASK count for Cursor (default 8, warns above 20)")
+    .option("--phase <name>", "Generate TASKs for a specific phase label only (e.g. 'MVP 4')")
+    .option("--scaffold", "Write skeleton TASK markdown files directly, without an LLM")
+    .option("--dry-run", "Print the plan without writing or modifying files")
+    .option("--cwd <path>", "Run against a different directory")
+    .action(async (options) => {
+    await taskGenerateCommand(options);
+});
+task
+    .command("start <taskId>")
+    .description("Confirm a clean working tree, create the task branch, record Status/Git context, and print a Builder prompt")
+    .option("--dry-run", "Print the plan without touching files or Git")
+    .option("--allow-dirty", "Proceed even if the Git working tree is dirty")
+    .option("--agent <name>", "Agent to build the prompt with (default `builder`)")
+    .option("--cwd <path>", "Run against a different directory")
+    .action(async (taskId, options) => {
+    await taskStartCommand(taskId, options);
+});
+task
+    .command("prompt <taskId>")
+    .description("Print a Cursor-ready prompt built from the TASK + agent context")
+    .option("--agent <name>", "Agent name (orchestrator / planner / architect / builder / reviewer / tester / docs / recovery)")
+    .option("--context <path...>", "Additional context file paths")
+    .option("--cwd <path>", "Inspect a different directory")
+    .action(async (taskId, options) => {
+    await agentPromptCommand(options.agent ?? "builder", taskId, {
+        cwd: options.cwd,
+        context: options.context,
+    });
+});
+task
+    .command("check <taskId>")
+    .description("Read-only check: git diff/log + acceptance criteria + doc updates + Result fields + a Reviewer prompt")
+    .option("--strict", "Exit with code 1 if any required item is missing")
+    .option("--agent <name>", "Agent to build the prompt with (default `reviewer`)")
+    .option("--cwd <path>", "Inspect a different directory")
+    .action(async (taskId, options) => {
+    await taskCheckCommand(taskId, options);
+});
+task
+    .command("done <taskId>")
+    .description("Validate Result/Test Result, move Status to Review, and print a commit message (no auto-commit)")
+    .option("--dry-run", "Print the plan without touching files")
+    .option("--finalize", "Move Status to Done instead of Review (use after human review)")
+    .option("--cwd <path>", "Run against a different directory")
+    .action(async (taskId, options) => {
+    await taskDoneCommand(taskId, options);
+});
+task
+    .command("rollback <taskId>")
+    .description("Default: advisory only. --confirm: non-destructive rollback. --confirm-destructive: hard reset.")
+    .option("--confirm", "Allow non-destructive rollback execution (branch-delete etc.)")
+    .option("--confirm-destructive", "Allow destructive rollback execution (reset --hard etc.)")
+    .option("--strategy <name>", "branch-delete | reset-base | revert-merge (default branch-delete)")
+    .option("--keep-branch", "Keep the task branch even when using branch-delete")
+    .option("--dry-run", "Print the plan without running any git commands, even with --confirm")
+    .option("--cwd <path>", "Run against a different directory")
+    .action(async (taskId, options) => {
+    await taskRollbackCommand(taskId, options);
+});
+task
+    .command("pull")
+    .description("Generate `docs/tasks/*.md` skeletons from Notion Tasks DB rows (defaults to Status = Planned)")
+    .option("--dry-run", "Print the plan without touching files or Notion")
+    .option("--json", "Print machine-readable JSON")
+    .option("--status <name>", "Notion Status values to pull (comma-separated, e.g. 'Planned,Ready'). Default `Planned`")
+    .option("--limit <number>", "Maximum rows to pull from Notion (default 20, max 100)")
+    .option("--cwd <path>", "Run against a different directory")
+    .option("--verbose", "Print a decision trace per considered row (taskId / pageId / docsPath / reason)")
+    .action(async (options) => {
+    await taskPullCommand(options);
+});
+const notion = program
+    .command("notion")
+    .description("Notion dashboard sync");
+notion
+    .command("init")
+    .description("Interactive setup: use arrow keys + Enter to pick Yes/No, then write `.vibeops.json` `notion` section and `.vibeops.env(.example)`")
+    .option("--dry-run", "Print the plan without changing files (no interactive prompts)")
+    .option("--enable", "Set `notion.enabled = true` and skip the first prompt")
+    .option("--projects-db <id>", "Set `notion.projectsDatabaseId` (skip the prompt)")
+    .option("--tasks-db <id>", "Set `notion.tasksDatabaseId` (skip the prompt)")
+    .option("--non-interactive", "Force non-interactive mode in a TTY (use flag values + safe defaults only)")
+    .option("--cwd <path>", "Run against a different directory")
+    .action(async (options) => {
+    await notionInitCommand(options);
+});
+notion
+    .command("test")
+    .description("Read-only check: Notion API auth + access to Projects/Tasks DBs + required-property schema validation")
+    .option("--json", "Print machine-readable JSON")
+    .option("--debug-shape", "Also print a token-safe diagnostic of the Projects/Tasks retrieve responses (top-level keys, data_sources, etc.)")
+    .option("--cwd <path>", "Run against a different directory")
+    .action(async (options) => {
+    await notionTestCommand(options);
+});
+notion
+    .command("sync")
+    .description("Push `docs/project` + `docs/tasks` metadata into Notion Projects/Tasks DBs (read-only on local files)")
+    .option("--dry-run", "Print the plan without any Notion mutation (queries only)")
+    .option("--json", "Print machine-readable JSON")
+    .option("--only-tasks", "Sync the Tasks DB only (leave the Project row alone)")
+    .option("--only-project", "Sync the Project DB only (leave Task rows alone)")
+    .option("--cwd <path>", "Run against a different directory")
+    .action(async (options) => {
+    await notionSyncCommand(options);
+});
+const github = program
+    .command("github")
+    .description("GitHub repository integration");
+github
+    .command("status")
+    .description("Read-only check: gh install/auth + git remotes + `.vibeops.json` github section + `package.json` repo fields")
+    .option("--json", "Print machine-readable JSON")
+    .option("--cwd <path>", "Inspect a different directory")
+    .action(async (options) => {
+    await githubStatusCommand(options);
+});
+github
+    .command("init")
+    .description("Interactive setup: check gh auth, manage the git remote, optionally `gh repo create`, then update `.vibeops.json` and `package.json`")
+    .option("--dry-run", "Print the plan without running gh / git or writing files")
+    .option("--yes", "Skip interactive prompts and use safe defaults")
+    .option("--owner <owner>", "GitHub owner (user or org)")
+    .option("--repo <repo>", "GitHub repo name")
+    .option("--public", "Force visibility = public (skip the prompt)")
+    .option("--private", "Force visibility = private (skip the prompt)")
+    .option("--remote <name>", "Git remote name (default `origin`)")
+    .option("--connect <ownerOrUrl>", "Connect to an existing repo instead of creating one (owner/repo or https/ssh URL)")
+    .option("--no-package-update", "Do not modify `package.json` repository/homepage/bugs fields")
+    .option("--cwd <path>", "Run against a different directory")
+    .action(async (options) => {
+    await githubInitCommand({
+        ...options,
+        // Commander turns `--no-package-update` into `packageUpdate: false`.
+        // Our command type still accepts the legacy `noPackageUpdate`
+        // shape for tests / direct invocation.
+        noPackageUpdate: options.packageUpdate === false,
+    });
+});
+program.parseAsync(process.argv).catch((err) => {
+    console.error("[vibeops] error:", err);
+    process.exitCode = 1;
+});

package/dist/commands/agent-list.js

@@ -0,0 +1,32 @@
+import { resolve } from "node:path";
+import { listAgents } from "../agent/loader.js";
+import { bold, dim, log } from "../lib/logger.js";
+import { projectPaths } from "../lib/paths.js";
+export async function agentListCommand(options = {}) {
+    const cwd = resolve(options.cwd ?? process.cwd());
+    const paths = projectPaths(cwd);
+    const agents = await listAgents(paths.vibeopsAgents);
+    if (options.json) {
+        const payload = agents.map((a) => ({
+            name: a.meta.name,
+            role: a.meta.role,
+            description: a.meta.description ?? null,
+            filePath: a.meta.filePath,
+        }));
+        log.raw(`${JSON.stringify(payload, null, 2)}\n`);
+        return;
+    }
+    if (agents.length === 0) {
+        log.warn(`No agents found in ${paths.vibeopsAgents}`);
+        log.info(dim("Run `vibeops init` first."));
+        process.exitCode = 1;
+        return;
+    }
+    log.info(bold("Agents"));
+    const nameWidth = Math.max(...agents.map((a) => a.meta.name.length));
+    for (const a of agents) {
+        const padded = a.meta.name.padEnd(nameWidth);
+        const summary = a.meta.description ?? a.meta.role;
+        log.info(`  ${padded}  ${dim(summary)}`);
+    }
+}

package/dist/commands/agent-prompt.js

@@ -0,0 +1,59 @@
+import { resolve } from "node:path";
+import { findAgent, listAgents } from "../agent/loader.js";
+import { buildPrompt } from "../agent/prompt.js";
+import { readConfig } from "../lib/config.js";
+import { readText } from "../lib/filesystem.js";
+import { log } from "../lib/logger.js";
+import { projectPaths } from "../lib/paths.js";
+import { readTaskFile, scanTasks } from "../lib/task.js";
+async function locateTaskFile(tasksDir, taskId) {
+    const all = await scanTasks(tasksDir);
+    const target = taskId.toUpperCase();
+    for (const t of all) {
+        if (t.id.toUpperCase() === target)
+            return t.filePath;
+    }
+    return null;
+}
+export async function agentPromptCommand(name, taskId, options = {}) {
+    const cwd = resolve(options.cwd ?? process.cwd());
+    const paths = projectPaths(cwd);
+    const agent = await findAgent(paths.vibeopsAgents, name);
+    if (!agent) {
+        const available = (await listAgents(paths.vibeopsAgents)).map((a) => a.meta.name);
+        log.error(`Unknown agent: "${name}".`);
+        if (available.length > 0) {
+            log.info(`Available: ${available.join(", ")}`);
+        }
+        else {
+            log.info(`No agents installed in ${paths.vibeopsAgents}. Run \`vibeops init\` first.`);
+        }
+        process.exitCode = 1;
+        return;
+    }
+    const config = await readConfig(paths.root);
+    let task;
+    const looksLikeTaskId = /^TASK-\d+/i.test(taskId);
+    if (looksLikeTaskId) {
+        const filePath = await locateTaskFile(paths.docsTasks, taskId);
+        if (!filePath) {
+            log.error(`TASK not found: ${taskId} (looked in ${paths.docsTasks})`);
+            process.exitCode = 1;
+            return;
+        }
+        const meta = await readTaskFile(filePath);
+        const body = await readText(filePath);
+        task = { meta, body };
+    }
+    else if (taskId !== "(unspecified)" && taskId.length > 0) {
+        log.warn(`"${taskId}" does not look like a TASK id (expected TASK-NNN). Continuing without TASK context.`);
+    }
+    const prompt = await buildPrompt({
+        agent,
+        config,
+        task,
+        projectRoot: paths.root,
+        contextPaths: options.context ?? [],
+    });
+    log.raw(prompt.endsWith("\n") ? prompt : `${prompt}\n`);
+}

package/dist/commands/agent-show.js

@@ -0,0 +1,26 @@
+import { resolve } from "node:path";
+import { findAgent, listAgents } from "../agent/loader.js";
+import { log } from "../lib/logger.js";
+import { projectPaths } from "../lib/paths.js";
+export async function agentShowCommand(name, options = {}) {
+    const cwd = resolve(options.cwd ?? process.cwd());
+    const paths = projectPaths(cwd);
+    const agent = await findAgent(paths.vibeopsAgents, name);
+    if (!agent) {
+        const available = (await listAgents(paths.vibeopsAgents)).map((a) => a.meta.name);
+        log.error(`Unknown agent: "${name}".`);
+        if (available.length > 0) {
+            log.info(`Available: ${available.join(", ")}`);
+        }
+        else {
+            log.info(`No agents installed in ${paths.vibeopsAgents}. Run \`vibeops init\` first.`);
+        }
+        process.exitCode = 1;
+        return;
+    }
+    if (options.raw) {
+        log.raw(agent.raw.endsWith("\n") ? agent.raw : `${agent.raw}\n`);
+        return;
+    }
+    log.raw(agent.body.endsWith("\n") ? agent.body : `${agent.body}\n`);
+}