git-vibe-setup 2.0.0

package/README.md

@@ -0,0 +1,11 @@
+# git-vibe-setup
+
+Local initializer for GitVibe consumer repositories.
+
+```bash
+npx --package=git-vibe-setup git-vibe-setup
+```
+
+The command writes `.github` and `.git-vibe` starter files, pins reusable
+workflow refs to the latest stable `markhuangai/git-vibe` release, and fails
+before writing if release lookup or target-file validation fails.

package/dist/cli.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+interface SetupCliRuntime {
+    cwd?: string;
+    error?: (message: string) => void;
+    fetchImpl?: typeof fetch;
+    log?: (message: string) => void;
+    repositoryRoot?: string;
+}
+export declare function runSetup(runtime?: SetupCliRuntime): Promise<void>;
+export declare function setupCli(runtime?: SetupCliRuntime): Promise<number>;
+export {};

package/dist/cli.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { fileURLToPath } from "node:url";
+import { blockingInstallPaths, buildInstallFiles, existingFilesError, installFiles, } from "./install.js";
+import { renderManualSetupInstructions } from "./instructions.js";
+import { latestStableReleaseTag } from "./releases.js";
+export async function runSetup(runtime = {}) {
+    const cwd = runtime.cwd || process.cwd();
+    const repositoryRoot = runtime.repositoryRoot || packageRoot();
+    const releaseTag = await latestStableReleaseTag(runtime.fetchImpl || fetch);
+    const files = buildInstallFiles({ cwd, releaseTag, repositoryRoot });
+    const blockingPaths = blockingInstallPaths(files);
+    if (blockingPaths.length > 0)
+        throw existingFilesError(blockingPaths, cwd);
+    installFiles(files);
+    (runtime.log || console.log)(renderManualSetupInstructions(releaseTag));
+}
+export async function setupCli(runtime = {}) {
+    try {
+        await runSetup(runtime);
+        return 0;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        (runtime.error || console.error)(message);
+        return 1;
+    }
+}
+function packageRoot() {
+    return fileURLToPath(new URL("../", import.meta.url));
+}
+/* c8 ignore start */
+if (isDirectRun(import.meta.url)) {
+    const exitCode = await setupCli();
+    process.exitCode = exitCode;
+}
+/* c8 ignore stop */
+function isDirectRun(moduleUrl, entrypoint = process.argv[1]) {
+    return Boolean(entrypoint && moduleUrl === pathToFileURL(resolve(entrypoint)).href);
+}

package/dist/install.d.ts

@@ -0,0 +1,14 @@
+export interface InstallFile {
+    content: string;
+    sourcePath: string;
+    targetPath: string;
+}
+export declare function buildInstallFiles(options: {
+    cwd: string;
+    releaseTag: string;
+    repositoryRoot: string;
+}): InstallFile[];
+export declare function blockingInstallPaths(files: InstallFile[]): string[];
+export declare function installFiles(files: InstallFile[]): void;
+export declare function existingFilesError(paths: string[], cwd: string): Error;
+export declare function pinWorkflowReleaseRefs(content: string, releaseTag: string): string;

package/dist/install.js

@@ -0,0 +1,94 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+export function buildInstallFiles(options) {
+    return installSources(options.repositoryRoot).flatMap((source) => listRelativeFiles(source.sourceDirectory).map((relativePath) => {
+        const sourcePath = join(source.sourceDirectory, relativePath);
+        const targetPath = join(options.cwd, source.targetDirectory, relativePath);
+        const content = readFileSync(sourcePath, "utf8");
+        return {
+            content: pinWorkflowReleaseRefs(content, options.releaseTag),
+            sourcePath,
+            targetPath,
+        };
+    }));
+}
+export function blockingInstallPaths(files) {
+    return files
+        .map((file) => file.targetPath)
+        .filter((targetPath) => existsSync(targetPath))
+        .sort();
+}
+export function installFiles(files) {
+    const createdDirectories = [];
+    const createdFiles = [];
+    try {
+        for (const file of files) {
+            ensureDirectory(dirname(file.targetPath), createdDirectories);
+            writeFileSync(file.targetPath, file.content, { flag: "wx" });
+            createdFiles.push(file.targetPath);
+        }
+    }
+    catch (error) {
+        rollbackInstall(createdFiles, createdDirectories);
+        throw error;
+    }
+}
+export function existingFilesError(paths, cwd) {
+    const listed = paths.map((path) => `- ${relative(cwd, path) || path}`).join("\n");
+    return new Error(`git-vibe-setup found existing GitVibe files and did not overwrite them:\n${listed}\nRemove the listed files before running setup again.`);
+}
+export function pinWorkflowReleaseRefs(content, releaseTag) {
+    return content.replace(/(uses:\s*markhuangai\/git-vibe\/\.github\/workflows\/[^\s@]+)@[^\s]+/g, (_match, workflowReference) => `${workflowReference}@${releaseTag}`);
+}
+function installSources(repositoryRoot) {
+    return [
+        {
+            sourceDirectory: join(repositoryRoot, "templates", ".github"),
+            targetDirectory: ".github",
+        },
+        {
+            sourceDirectory: join(repositoryRoot, "templates", ".git-vibe"),
+            targetDirectory: ".git-vibe",
+        },
+    ];
+}
+function listRelativeFiles(directory) {
+    return readdirSync(directory, { withFileTypes: true })
+        .flatMap((entry) => {
+        const entryPath = join(directory, entry.name);
+        if (entry.isDirectory()) {
+            return listRelativeFiles(entryPath).map((path) => join(entry.name, path));
+        }
+        /* c8 ignore next */
+        return entry.isFile() ? [entry.name] : [];
+    })
+        .sort();
+}
+function ensureDirectory(directory, createdDirectories) {
+    const missing = missingDirectories(directory);
+    for (const path of missing) {
+        mkdirSync(path);
+        createdDirectories.push(path);
+    }
+}
+function missingDirectories(directory) {
+    const missing = [];
+    let current = directory;
+    while (!existsSync(current)) {
+        missing.push(current);
+        const parent = dirname(current);
+        /* c8 ignore next */
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return missing.reverse();
+}
+function rollbackInstall(createdFiles, createdDirectories) {
+    for (const file of [...createdFiles].reverse()) {
+        rmSync(file, { force: true });
+    }
+    for (const directory of [...createdDirectories].reverse()) {
+        rmSync(directory, { force: true, recursive: false });
+    }
+}

package/dist/instructions.d.ts

@@ -0,0 +1 @@
+export declare function renderManualSetupInstructions(releaseTag: string): string;

package/dist/instructions.js

@@ -0,0 +1,25 @@
+const requiredSecrets = [
+    ["GITVIBE_AI_ENV_JSON", "JSON env bundle for AI provider config and CLI auth."],
+    ["GITVIBE_GITHUB_TOKEN", "Fine-grained PAT for GitVibe workflow and server writes."],
+    ["WEBHOOK_SECRET", "Webhook shared secret mapped to GITHUB_WEBHOOK_SECRET in deployment."],
+];
+const usefulVariables = [
+    "GITVIBE_BASE_BRANCH",
+    "GITVIBE_DISCUSSION_CATEGORY",
+    "GITVIBE_RUNNER",
+    "GITVIBE_LOG_LEVEL",
+];
+export function renderManualSetupInstructions(releaseTag) {
+    const lines = [
+        `GitVibe starter files installed with reusable workflows pinned to ${releaseTag}.`,
+        "",
+        "Configure these GitHub secrets manually before running the workflows:",
+        ...requiredSecrets.map(([name, description]) => `- ${name}: ${description}`),
+        "",
+        "Optional repository variables:",
+        ...usefulVariables.map((name) => `- ${name}`),
+        "",
+        `Reference bundle shape: https://github.com/markhuangai/git-vibe/blob/${releaseTag}/examples/consumer/GITVIBE_AI_ENV_JSON.example.json`,
+    ];
+    return lines.join("\n");
+}

package/dist/releases.d.ts

@@ -0,0 +1,11 @@
+export interface GitHubRelease {
+    created_at?: string;
+    draft?: boolean;
+    prerelease?: boolean;
+    published_at?: string;
+    tag_name?: string;
+}
+export declare class ReleaseLookupError extends Error {
+}
+export declare function latestStableReleaseTag(fetchImpl?: typeof fetch): Promise<string>;
+export declare function selectLatestStableRelease(releases: GitHubRelease[]): GitHubRelease | undefined;

package/dist/releases.js

@@ -0,0 +1,65 @@
+export class ReleaseLookupError extends Error {
+}
+const releasesUrl = "https://api.github.com/repos/markhuangai/git-vibe/releases";
+const releasesPerPage = 100;
+export async function latestStableReleaseTag(fetchImpl = fetch) {
+    const releases = await fetchReleases(fetchImpl);
+    const release = selectLatestStableRelease(releases);
+    if (!release?.tag_name) {
+        throw new ReleaseLookupError("git-vibe-setup could not check the latest GitVibe update because no stable release is available. No files were written.");
+    }
+    return release.tag_name;
+}
+export function selectLatestStableRelease(releases) {
+    return releases
+        .filter((release) => !release.draft && !release.prerelease && release.tag_name)
+        .sort(compareReleaseFreshness)[0];
+}
+async function fetchReleases(fetchImpl) {
+    const releases = [];
+    for (let page = 1;; page += 1) {
+        const data = await fetchReleasePage(fetchImpl, page);
+        releases.push(...data);
+        if (data.length < releasesPerPage)
+            return releases;
+    }
+}
+async function fetchReleasePage(fetchImpl, page) {
+    let response;
+    try {
+        response = await fetchImpl(releasePageUrl(page), {
+            headers: {
+                accept: "application/vnd.github+json",
+                "user-agent": "git-vibe-setup",
+                "x-github-api-version": "2022-11-28",
+            },
+        });
+    }
+    catch {
+        throw unavailableReleaseError();
+    }
+    if (!response.ok)
+        throw unavailableReleaseError();
+    try {
+        const data = await response.json();
+        return Array.isArray(data) ? data : [];
+    }
+    catch {
+        throw unavailableReleaseError();
+    }
+}
+function releasePageUrl(page) {
+    const url = new URL(releasesUrl);
+    url.searchParams.set("page", String(page));
+    url.searchParams.set("per_page", String(releasesPerPage));
+    return url.toString();
+}
+function compareReleaseFreshness(left, right) {
+    return releaseTime(right) - releaseTime(left);
+}
+function releaseTime(release) {
+    return Date.parse(release.published_at || release.created_at || "") || 0;
+}
+function unavailableReleaseError() {
+    return new ReleaseLookupError("git-vibe-setup could not check the latest GitVibe update because the GitHub release service is unavailable. No files were written.");
+}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "git-vibe-setup",
+  "version": "2.0.0",
+  "private": false,
+  "type": "module",
+  "bin": {
+    "git-vibe-setup": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "check": "prettier --check . && eslint . && corepack pnpm typecheck && corepack pnpm test && corepack pnpm build",
+    "test": "vitest run",
+    "typecheck": "tsc --project tsconfig.json --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.5"
+  }
+}

package/templates/.git-vibe/role-group/correctness.md

@@ -0,0 +1,7 @@
+# Correctness Reviewer
+
+Review the stage result for behavioral correctness. Check that conclusions are
+grounded in the GitHub context and repository evidence, and that any required
+next action is specific enough to execute.
+
+Return only the current stage schema.

package/templates/.git-vibe/role-group/maintainability.md

@@ -0,0 +1,7 @@
+# Maintainability Reviewer
+
+Review the stage result for implementation clarity, long-term maintenance,
+operability, and fit with existing repository patterns. Prefer small,
+evidence-backed changes over broad redesigns.
+
+Return only the current stage schema.

package/templates/.git-vibe/role-group/security.md

@@ -0,0 +1,7 @@
+# Security Reviewer
+
+Review the stage result for token handling, permissions, untrusted input, file
+access, workflow authority, and GitHub write safety. Flag only concrete risks
+that affect the requested work.
+
+Return only the current stage schema.

package/templates/.github/git-vibe.yml

@@ -0,0 +1,105 @@
+# Copy this file to .github/git-vibe.yml in the consumer repository.
+
+version: 1
+
+branches:
+  base: ""
+
+runner:
+  default: ubuntu-latest
+
+github_auth:
+  mode: webhook-pat
+  # GitHub Actions Secret name. Stores the GitHub write token.
+  token_secret: GITVIBE_GITHUB_TOKEN
+
+ai:
+  default_profile: local_proxy
+  profiles:
+    local_proxy:
+      enabled: true
+      adapter: ai-sdk-agentool
+      provider:
+        type: openai-compatible # openai | anthropic | openai-compatible
+        # Model names are configuration, not credentials.
+        model: glm-5
+        # Keys inside GITVIBE_AI_ENV_JSON.
+        base_url:
+          from_bundle: GITVIBE_AI_BASE_URL
+        api_key:
+          from_bundle: GITVIBE_AI_API_KEY
+      reasoning:
+        effort: high
+      generation:
+        temperature: 0.2
+        max_output_tokens: 6000
+        max_steps: 90
+    codex_cli:
+      enabled: false
+      adapter: cli-codex
+      # Key inside GITVIBE_AI_ENV_JSON. Stores compact auth.json contents.
+      auth_json:
+        from_bundle: CODEX_AUTH_JSON
+      model: gpt-5.3-codex
+      reasoning:
+        effort: high
+        summary: concise
+    claude_code:
+      enabled: false
+      adapter: cli-claude-code
+      # Key inside GITVIBE_AI_ENV_JSON. Stores the Claude Code OAuth access token.
+      env:
+        CLAUDE_CODE_OAUTH_TOKEN:
+          from_bundle: CLAUDE_OAUTH_TOKEN
+      model: opus
+      reasoning:
+        effort: xhigh
+  role_groups:
+    review_gate:
+      synthesizer: local_proxy
+      parallel: 2
+      roles:
+        - role: correctness.md
+          profile: local_proxy
+        - role: security.md
+          profile: local_proxy
+        - role: maintainability.md
+          profile: local_proxy
+  budgets:
+    default_timeout_minutes: 60
+    implementation_timeout_minutes: 120
+    feedback_timeout_minutes: 120
+    publish_timeout_minutes: 15
+    default_max_turns: 90
+    implementation_max_turns: 120
+    feedback_max_turns: 120
+  stages:
+    investigate:
+      role_group: review_gate
+    validate:
+      role_group: review_gate
+    decompose:
+      profile: local_proxy
+    materialize:
+      profile: local_proxy
+    review-matrix:
+      role_group: review_gate
+    implement:
+      profile: local_proxy
+    create-pr:
+      profile: local_proxy
+    address-pr-feedback:
+      profile: local_proxy
+
+bug_investigation:
+  auto_start_on_new_bug: false
+  community_trigger:
+    enabled: false
+    reaction: "+1"
+    threshold: 6
+    eligible_labels:
+      - git-vibe:bug
+    dispatch: investigate
+
+tests:
+  commands: []

package/templates/.github/workflows/address-feedback.yml

@@ -0,0 +1,34 @@
+name: GitVibe address feedback
+run-name: "[git-vibe][address-feedback]: PR #${{ inputs.pr-number }}"
+
+on:
+  workflow_dispatch:
+    inputs:
+      pr-number:
+        description: Pull request number with feedback to address.
+        required: true
+        type: string
+      dry-run:
+        description: Validate without writing to GitHub.
+        required: false
+        type: boolean
+        default: false
+      source-comment:
+        description: JSON source comment metadata for replying to command comments.
+        required: false
+        type: string
+        default: ""
+
+jobs:
+  address-feedback:
+    uses: markhuangai/git-vibe/.github/workflows/address-feedback.yml@v2
+    with:
+      pr-number: ${{ inputs.pr-number }}
+      runner: ubuntu-latest
+      timeout_minutes: 120
+      max_turns: 120
+      dry-run: ${{ inputs.dry-run }}
+      source-comment: ${{ inputs.source-comment }}
+    secrets:
+      GITVIBE_GITHUB_TOKEN: ${{ secrets.GITVIBE_GITHUB_TOKEN }}
+      GITVIBE_AI_ENV_JSON: ${{ secrets.GITVIBE_AI_ENV_JSON }}

package/templates/.github/workflows/decompose.yml

@@ -0,0 +1,34 @@
+name: GitVibe decompose
+run-name: "[git-vibe][decompose]: Discussion #${{ inputs.discussion-number }}"
+
+on:
+  workflow_dispatch:
+    inputs:
+      discussion-number:
+        description: Discussion number to decompose.
+        required: true
+        type: string
+      dry-run:
+        description: Validate without writing to GitHub.
+        required: false
+        type: boolean
+        default: false
+      source-comment:
+        description: JSON source comment metadata for replying to command comments.
+        required: false
+        type: string
+        default: ""
+
+jobs:
+  decompose:
+    uses: markhuangai/git-vibe/.github/workflows/decompose.yml@v2
+    with:
+      discussion-number: ${{ inputs.discussion-number }}
+      runner: ubuntu-latest
+      timeout_minutes: 60
+      max_turns: 90
+      dry-run: ${{ inputs.dry-run }}
+      source-comment: ${{ inputs.source-comment }}
+    secrets:
+      GITVIBE_GITHUB_TOKEN: ${{ secrets.GITVIBE_GITHUB_TOKEN }}
+      GITVIBE_AI_ENV_JSON: ${{ secrets.GITVIBE_AI_ENV_JSON }}

package/templates/.github/workflows/develop.yml

@@ -0,0 +1,39 @@
+name: GitVibe develop
+run-name: "[git-vibe][develop]: Issue #${{ inputs.issue-number }}"
+
+on:
+  workflow_dispatch:
+    inputs:
+      issue-number:
+        description: Approved implementation issue number.
+        required: true
+        type: string
+      dry-run:
+        description: Validate without writing to GitHub.
+        required: false
+        type: boolean
+        default: false
+      source-comment:
+        description: JSON source comment metadata for replying to command comments.
+        required: false
+        type: string
+        default: ""
+
+jobs:
+  develop:
+    uses: markhuangai/git-vibe/.github/workflows/develop.yml@v2
+    with:
+      issue-number: ${{ inputs.issue-number }}
+      runner: ubuntu-latest
+      implementation_timeout_minutes: 120
+      review_timeout_minutes: 60
+      publish_timeout_minutes: 15
+      max_turns: 90
+      implementation_max_turns: 120
+      validation_repair_attempts: 2
+      validation_repair_max_turns: 90
+      dry-run: ${{ inputs.dry-run }}
+      source-comment: ${{ inputs.source-comment }}
+    secrets:
+      GITVIBE_GITHUB_TOKEN: ${{ secrets.GITVIBE_GITHUB_TOKEN }}
+      GITVIBE_AI_ENV_JSON: ${{ secrets.GITVIBE_AI_ENV_JSON }}

package/templates/.github/workflows/investigate.yml

@@ -0,0 +1,34 @@
+name: GitVibe investigate
+run-name: "[git-vibe][investigate]: Issue #${{ inputs.issue-number }}"
+
+on:
+  workflow_dispatch:
+    inputs:
+      issue-number:
+        description: Issue number to investigate.
+        required: true
+        type: string
+      dry-run:
+        description: Validate without writing to GitHub.
+        required: false
+        type: boolean
+        default: false
+      source-comment:
+        description: JSON source comment metadata for replying to command comments.
+        required: false
+        type: string
+        default: ""
+
+jobs:
+  investigate:
+    uses: markhuangai/git-vibe/.github/workflows/investigate.yml@v2
+    with:
+      issue-number: ${{ inputs.issue-number }}
+      runner: ubuntu-latest
+      timeout_minutes: 60
+      max_turns: 90
+      dry-run: ${{ inputs.dry-run }}
+      source-comment: ${{ inputs.source-comment }}
+    secrets:
+      GITVIBE_GITHUB_TOKEN: ${{ secrets.GITVIBE_GITHUB_TOKEN }}
+      GITVIBE_AI_ENV_JSON: ${{ secrets.GITVIBE_AI_ENV_JSON }}

package/templates/.github/workflows/materialize.yml

@@ -0,0 +1,34 @@
+name: GitVibe materialize
+run-name: "[git-vibe][materialize]: Discussion #${{ inputs.discussion-number }}"
+
+on:
+  workflow_dispatch:
+    inputs:
+      discussion-number:
+        description: Discussion number to materialize.
+        required: true
+        type: string
+      dry-run:
+        description: Validate without writing to GitHub.
+        required: false
+        type: boolean
+        default: false
+      source-comment:
+        description: JSON source comment metadata for replying to command comments.
+        required: false
+        type: string
+        default: ""
+
+jobs:
+  materialize:
+    uses: markhuangai/git-vibe/.github/workflows/materialize.yml@v2
+    with:
+      discussion-number: ${{ inputs.discussion-number }}
+      runner: ubuntu-latest
+      timeout_minutes: 60
+      max_turns: 90
+      dry-run: ${{ inputs.dry-run }}
+      source-comment: ${{ inputs.source-comment }}
+    secrets:
+      GITVIBE_GITHUB_TOKEN: ${{ secrets.GITVIBE_GITHUB_TOKEN }}
+      GITVIBE_AI_ENV_JSON: ${{ secrets.GITVIBE_AI_ENV_JSON }}

package/templates/.github/workflows/validate.yml

@@ -0,0 +1,41 @@
+name: GitVibe validate
+run-name: "[git-vibe][validate]: ${{ inputs.discussion-number != '' && format('Discussion #{0}', inputs.discussion-number) || inputs.issue-number != '' && format('Issue #{0}', inputs.issue-number) || 'Artifact' }}"
+
+on:
+  workflow_dispatch:
+    inputs:
+      issue-number:
+        description: Issue number to validate.
+        required: false
+        type: string
+        default: ""
+      discussion-number:
+        description: Discussion number to validate.
+        required: false
+        type: string
+        default: ""
+      dry-run:
+        description: Validate without writing to GitHub.
+        required: false
+        type: boolean
+        default: false
+      source-comment:
+        description: JSON source comment metadata for replying to command comments.
+        required: false
+        type: string
+        default: ""
+
+jobs:
+  validate:
+    uses: markhuangai/git-vibe/.github/workflows/validate.yml@v2
+    with:
+      issue-number: ${{ inputs.issue-number }}
+      discussion-number: ${{ inputs.discussion-number }}
+      runner: ubuntu-latest
+      timeout_minutes: 60
+      max_turns: 90
+      dry-run: ${{ inputs.dry-run }}
+      source-comment: ${{ inputs.source-comment }}
+    secrets:
+      GITVIBE_GITHUB_TOKEN: ${{ secrets.GITVIBE_GITHUB_TOKEN }}
+      GITVIBE_AI_ENV_JSON: ${{ secrets.GITVIBE_AI_ENV_JSON }}

package/templates/GITVIBE_AI_ENV_JSON.example.json

@@ -0,0 +1,8 @@
+{
+  "CLAUDE_OAUTH_TOKEN": "replace-with-claude-oauth-token",
+  "CODEX_AUTH_JSON": "{\"tokens\":[]}",
+  "GITVIBE_AI_API_KEY": "replace-with-ai-provider-api-key",
+  "GITVIBE_AI_BASE_URL": "https://api.provider.example/v1",
+  "MINIMAX_API_KEY": "replace-with-minimax-api-key",
+  "MINIMAX_ANTHROPIC_BASE_URL": "https://api.minimax.example/anthropic"
+}