git-vibe-setup 3.0.2 → 3.1.0

package/README.md

@@ -6,6 +6,34 @@ Local initializer for GitVibe consumer repositories.
 npx git-vibe-setup setup
 ```
 
-The `setup` 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.
+The `setup` command fetches `examples/consumer` from the latest stable
+`markhuangai/git-vibe` release, writes `.github` and `.git-vibe` starter files,
+pins reusable workflow refs to that release, and fails before writing if release
+lookup, starter fetch, or target-file validation fails.
+
+When `GITHUB_TOKEN` or `GH_TOKEN` is set, `git-vibe-setup` uses it only to
+authenticate GitHub release and starter-file reads. This avoids anonymous API
+throttling in CI and shared-network environments.
+
+```bash
+npx git-vibe-setup update
+```
+
+The `update` command fetches `examples/consumer` from the latest stable
+`markhuangai/git-vibe` release, rewrites only `.github/workflows/*.yml` GitVibe
+wrapper files, and pins them to that release. It does not update
+`.github/git-vibe.yml`, `.git-vibe`, secrets, or variables, and it refuses to
+overwrite workflow files that do not look like GitVibe wrappers.
+
+To test a specific release or prerelease from a consumer repository, pass the
+release tag explicitly:
+
+```bash
+npx git-vibe-setup update --release v3.0.4-rc.1
+```
+
+To let automatic latest-release lookup choose prereleases, opt in explicitly:
+
+```bash
+npx git-vibe-setup update --include-prereleases
+```

package/dist/cli.d.ts

@@ -4,10 +4,13 @@ interface SetupCliRuntime {
     cwd?: string;
     error?: (message: string) => void;
     fetchImpl?: typeof fetch;
+    githubToken?: string;
+    includePrereleases?: boolean;
     log?: (message: string) => void;
-    repositoryRoot?: string;
+    releaseTag?: string;
 }
 export declare function runSetup(runtime?: SetupCliRuntime): Promise<void>;
+export declare function runUpdate(runtime?: SetupCliRuntime): Promise<void>;
 export declare function setupCli(runtime?: SetupCliRuntime): Promise<number>;
 export declare function isDirectRun(moduleUrl: string, entrypoint?: string): boolean;
 export {};

package/dist/cli.js

@@ -3,42 +3,79 @@ import { realpathSync } from "node:fs";
 import { resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { fileURLToPath } from "node:url";
-import { blockingInstallPaths, buildInstallFiles, existingFilesError, installFiles, } from "./install.js";
+import { fetchConsumerStarterFiles } from "./consumer-starter.js";
+import { githubTokenFromEnvironment } from "./github-api.js";
+import { blockingInstallPaths, buildInstallFiles, buildWorkflowUpdateFiles, existingFilesError, installFiles, unmanagedWorkflowUpdateError, unmanagedWorkflowUpdatePaths, updateFiles, } from "./install.js";
 import { renderManualSetupInstructions } from "./instructions.js";
-import { latestStableReleaseTag } from "./releases.js";
+import { latestReleaseTag } from "./releases.js";
 const usage = `Usage:
-  git-vibe-setup setup
+  git-vibe-setup setup [--release <tag>] [--include-prereleases]
+  git-vibe-setup update [--release <tag>] [--include-prereleases]
   git-vibe-setup
 
 Commands:
   setup   Install GitVibe starter files into the current repository.
+  update  Update GitVibe workflow wrapper files in the current repository.
 
 Options:
-  -h, --help   Show this help message.`;
+  --release <tag>         Use a specific GitVibe release tag, including prereleases.
+  --include-prereleases   Allow latest-release lookup to select prereleases.
+  -h, --help              Show this help message.`;
 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 fetchImpl = runtime.fetchImpl || fetch;
+    const githubToken = runtime.githubToken || githubTokenFromEnvironment();
+    const releaseTag = await resolveReleaseTag(runtime, fetchImpl, githubToken);
+    const sourceFiles = await fetchConsumerStarterFiles({ fetchImpl, githubToken, releaseTag });
+    const files = buildInstallFiles({ cwd, releaseTag, sourceFiles });
     const blockingPaths = blockingInstallPaths(files);
     if (blockingPaths.length > 0)
         throw existingFilesError(blockingPaths, cwd);
     installFiles(files);
     (runtime.log || console.log)(renderManualSetupInstructions(releaseTag));
 }
+export async function runUpdate(runtime = {}) {
+    const cwd = runtime.cwd || process.cwd();
+    const fetchImpl = runtime.fetchImpl || fetch;
+    const githubToken = runtime.githubToken || githubTokenFromEnvironment();
+    const releaseTag = await resolveReleaseTag(runtime, fetchImpl, githubToken);
+    const sourceFiles = await fetchConsumerStarterFiles({ fetchImpl, githubToken, releaseTag });
+    const files = buildWorkflowUpdateFiles({ cwd, releaseTag, sourceFiles });
+    const unmanagedPaths = unmanagedWorkflowUpdatePaths(files);
+    if (unmanagedPaths.length > 0)
+        throw unmanagedWorkflowUpdateError(unmanagedPaths, cwd);
+    updateFiles(files);
+    (runtime.log || console.log)(`GitVibe workflow files updated with reusable workflows pinned to ${releaseTag}.`);
+}
 export async function setupCli(runtime = {}) {
     const argv = runtime.argv || process.argv.slice(2);
-    const command = argv[0] || "setup";
-    if (command === "--help" || command === "-h" || command === "help") {
+    let parsed;
+    try {
+        parsed = parseCliOptions(argv);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        (runtime.error || console.error)(`${message}\n\n${usage}`);
+        return 1;
+    }
+    if (parsed.kind === "help") {
         (runtime.log || console.log)(usage);
         return 0;
     }
-    if (command !== "setup") {
-        (runtime.error || console.error)(`Unknown command: ${command}\n\n${usage}`);
+    if (parsed.kind === "error") {
+        (runtime.error || console.error)(`${parsed.message}\n\n${usage}`);
         return 1;
     }
+    const commandRuntime = {
+        ...runtime,
+        includePrereleases: runtime.includePrereleases || parsed.options.includePrereleases,
+        releaseTag: parsed.options.releaseTag || runtime.releaseTag,
+    };
     try {
-        await runSetup(runtime);
+        if (parsed.options.command === "update")
+            await runUpdate(commandRuntime);
+        else
+            await runSetup(commandRuntime);
         return 0;
     }
     catch (error) {
@@ -47,8 +84,70 @@ export async function setupCli(runtime = {}) {
         return 1;
     }
 }
-function packageRoot() {
-    return fileURLToPath(new URL("../", import.meta.url));
+async function resolveReleaseTag(runtime, fetchImpl, githubToken) {
+    if (runtime.releaseTag)
+        return validateReleaseTag(runtime.releaseTag);
+    const releaseTag = await latestReleaseTag({
+        fetchImpl,
+        githubToken,
+        includePrereleases: runtime.includePrereleases,
+    });
+    return validateReleaseTag(releaseTag);
+}
+function parseCliOptions(argv) {
+    if (argv.includes("--help") || argv.includes("-h") || argv[0] === "help") {
+        return { kind: "help" };
+    }
+    const command = commandName(argv[0]);
+    if (argv[0] && !command && !argv[0].startsWith("-")) {
+        return { kind: "error", message: `Unknown command: ${argv[0]}` };
+    }
+    const options = parseOptionArgs(command ? argv.slice(1) : argv);
+    if (options.kind !== "command")
+        return options;
+    return {
+        kind: "command",
+        options: {
+            ...options.options,
+            command: command || "setup",
+        },
+    };
+}
+function parseOptionArgs(args) {
+    const options = { includePrereleases: false };
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index] || "";
+        if (arg === "--include-prereleases") {
+            options.includePrereleases = true;
+        }
+        else if (arg === "--release") {
+            index += 1;
+            const releaseTag = args[index];
+            if (!releaseTag || releaseTag.startsWith("-")) {
+                return { kind: "error", message: "--release requires a release tag" };
+            }
+            options.releaseTag = validateReleaseTag(releaseTag);
+        }
+        else if (arg.startsWith("--release=")) {
+            options.releaseTag = validateReleaseTag(arg.slice("--release=".length));
+        }
+        else {
+            return { kind: "error", message: `Unknown option: ${arg}` };
+        }
+    }
+    return { kind: "command", options };
+}
+function commandName(value) {
+    if (value === "setup" || value === "update")
+        return value;
+    return undefined;
+}
+function validateReleaseTag(releaseTag) {
+    const trimmed = releaseTag.trim();
+    if (/^v?\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(trimmed)) {
+        return trimmed;
+    }
+    throw new Error(`Invalid release tag: ${releaseTag}. Release tags must look like v3.0.4 or v3.0.4-rc.1.`);
 }
 /* c8 ignore start */
 if (isDirectRun(import.meta.url)) {

package/dist/consumer-starter.d.ts

@@ -0,0 +1,10 @@
+export interface ConsumerStarterFile {
+    content: string;
+    relativePath: string;
+    sourcePath: string;
+}
+export declare function fetchConsumerStarterFiles(options: {
+    fetchImpl?: typeof fetch;
+    githubToken?: string;
+    releaseTag: string;
+}): Promise<ConsumerStarterFile[]>;

package/dist/consumer-starter.js

@@ -0,0 +1,116 @@
+import { githubApiHeaders } from "./github-api.js";
+const consumerStarterRoot = "examples/consumer";
+const repositoryContentsUrl = "https://api.github.com/repos/markhuangai/git-vibe/contents";
+const maxStarterFileBytes = 128 * 1024;
+export async function fetchConsumerStarterFiles(options) {
+    const fetchImpl = options.fetchImpl || fetch;
+    const files = await fetchDirectoryFiles(fetchImpl, options.releaseTag, consumerStarterRoot, options.githubToken);
+    if (files.length === 0) {
+        throw invalidStarterBundleError(options.releaseTag, `${consumerStarterRoot} contains no files`);
+    }
+    return files.sort((left, right) => left.relativePath.localeCompare(right.relativePath));
+}
+async function fetchDirectoryFiles(fetchImpl, releaseTag, path, githubToken) {
+    const data = await fetchGitHubJson(fetchImpl, contentsUrl(path, releaseTag), releaseTag, githubToken);
+    if (!Array.isArray(data)) {
+        throw invalidStarterBundleError(releaseTag, `${path} is not a directory`);
+    }
+    const fileGroups = await Promise.all(data.map((entry) => fetchEntryFiles(fetchImpl, releaseTag, asContentEntry(entry), githubToken)));
+    return fileGroups.flat();
+}
+async function fetchEntryFiles(fetchImpl, releaseTag, entry, githubToken) {
+    const path = entryPath(entry, releaseTag);
+    relativeConsumerPath(path, releaseTag);
+    const type = entryType(entry, releaseTag, path);
+    if (type === "dir")
+        return fetchDirectoryFiles(fetchImpl, releaseTag, path, githubToken);
+    if (type === "file")
+        return [await fetchFile(fetchImpl, releaseTag, path, githubToken)];
+    throw invalidStarterBundleError(releaseTag, `${path} has unsupported type ${type}`);
+}
+async function fetchFile(fetchImpl, releaseTag, path, githubToken) {
+    const data = asContentEntry(await fetchGitHubJson(fetchImpl, contentsUrl(path, releaseTag), releaseTag, githubToken));
+    if (data.type !== "file" || typeof data.content !== "string" || data.encoding !== "base64") {
+        throw invalidStarterBundleError(releaseTag, `${path} is not a base64 file`);
+    }
+    const encodedContent = data.content.replace(/\s/g, "");
+    if (!/^[A-Za-z0-9+/=]*$/.test(encodedContent)) {
+        throw invalidStarterBundleError(releaseTag, `${path} has invalid base64 content`);
+    }
+    const content = Buffer.from(encodedContent, "base64");
+    if (content.byteLength > maxStarterFileBytes) {
+        throw invalidStarterBundleError(releaseTag, `${path} is larger than 128KiB`);
+    }
+    return {
+        content: content.toString("utf8"),
+        relativePath: relativeConsumerPath(path, releaseTag),
+        sourcePath: path,
+    };
+}
+async function fetchGitHubJson(fetchImpl, url, releaseTag, githubToken) {
+    let response;
+    const headers = githubApiHeaders(githubToken);
+    try {
+        response = await fetchImpl(url, {
+            headers,
+        });
+    }
+    catch {
+        throw unavailableStarterBundleError(releaseTag);
+    }
+    if (!response.ok)
+        throw unavailableStarterBundleError(releaseTag);
+    try {
+        return await response.json();
+    }
+    catch {
+        throw unavailableStarterBundleError(releaseTag);
+    }
+}
+function contentsUrl(path, releaseTag) {
+    const url = new URL(`${repositoryContentsUrl}/${encodePath(path)}`);
+    url.searchParams.set("ref", releaseTag);
+    return url;
+}
+function encodePath(path) {
+    return path.split("/").map(encodeURIComponent).join("/");
+}
+function asContentEntry(value) {
+    return typeof value === "object" && value !== null ? value : {};
+}
+function entryPath(entry, releaseTag) {
+    if (typeof entry.path !== "string") {
+        throw invalidStarterBundleError(releaseTag, "a content entry is missing path");
+    }
+    return entry.path;
+}
+function entryType(entry, releaseTag, path) {
+    if (typeof entry.type !== "string") {
+        throw invalidStarterBundleError(releaseTag, `${path} is missing type`);
+    }
+    return entry.type;
+}
+function relativeConsumerPath(path, releaseTag) {
+    const prefix = `${consumerStarterRoot}/`;
+    if (!path.startsWith(prefix)) {
+        throw invalidStarterBundleError(releaseTag, `${path} is outside ${consumerStarterRoot}`);
+    }
+    const relativePath = path.slice(prefix.length);
+    if (!isSafeRelativePath(relativePath)) {
+        throw invalidStarterBundleError(releaseTag, `${path} has an unsafe relative path`);
+    }
+    return relativePath;
+}
+function isSafeRelativePath(relativePath) {
+    const segments = relativePath.split("/");
+    return (relativePath.length > 0 &&
+        !relativePath.startsWith("/") &&
+        !relativePath.includes("\\") &&
+        segments.every((segment) => segment.length > 0 && segment !== "." && segment !== ".."));
+}
+function unavailableStarterBundleError(releaseTag) {
+    return new Error(`git-vibe-setup could not fetch the GitVibe consumer starter from markhuangai/git-vibe@${releaseTag} because the GitHub content service is unavailable. No files were written.`);
+}
+function invalidStarterBundleError(releaseTag, detail) {
+    return new Error(`git-vibe-setup found an invalid GitVibe consumer starter at markhuangai/git-vibe@${releaseTag}: ${detail}. No files were written.`);
+}

package/dist/github-api.d.ts

@@ -0,0 +1,2 @@
+export declare function githubApiHeaders(githubToken?: string): Record<string, string>;
+export declare function githubTokenFromEnvironment(env?: Record<string, string | undefined>): string | undefined;

package/dist/github-api.js

@@ -0,0 +1,24 @@
+const defaultGitHubApiHeaders = {
+    accept: "application/vnd.github+json",
+    "user-agent": "git-vibe-setup",
+    "x-github-api-version": "2022-11-28",
+};
+export function githubApiHeaders(githubToken) {
+    const headers = { ...defaultGitHubApiHeaders };
+    const token = normalizeGitHubToken(githubToken);
+    if (token)
+        headers.authorization = `Bearer ${token}`;
+    return headers;
+}
+export function githubTokenFromEnvironment(env = process.env) {
+    return normalizeGitHubToken(env.GITHUB_TOKEN) || normalizeGitHubToken(env.GH_TOKEN);
+}
+function normalizeGitHubToken(githubToken) {
+    const token = githubToken?.trim();
+    if (!token)
+        return undefined;
+    if (/[\r\n]/.test(token)) {
+        throw new Error("git-vibe-setup found an invalid GitHub token value. No files were written.");
+    }
+    return token;
+}

package/dist/install.d.ts

@@ -1,3 +1,4 @@
+import type { ConsumerStarterFile } from "./consumer-starter.js";
 export interface InstallFile {
     content: string;
     sourcePath: string;
@@ -6,9 +7,17 @@ export interface InstallFile {
 export declare function buildInstallFiles(options: {
     cwd: string;
     releaseTag: string;
-    repositoryRoot: string;
+    sourceFiles: ConsumerStarterFile[];
+}): InstallFile[];
+export declare function buildWorkflowUpdateFiles(options: {
+    cwd: string;
+    releaseTag: string;
+    sourceFiles: ConsumerStarterFile[];
 }): InstallFile[];
 export declare function blockingInstallPaths(files: InstallFile[]): string[];
+export declare function unmanagedWorkflowUpdatePaths(files: InstallFile[]): string[];
 export declare function installFiles(files: InstallFile[]): void;
+export declare function updateFiles(files: InstallFile[]): void;
 export declare function existingFilesError(paths: string[], cwd: string): Error;
+export declare function unmanagedWorkflowUpdateError(paths: string[], cwd: string): Error;
 export declare function pinWorkflowReleaseRefs(content: string, releaseTag: string): string;

package/dist/install.js

@@ -1,16 +1,29 @@
-import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { dirname, join, relative } from "node:path";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, relative } from "node:path";
+const requiredInstallSourcePaths = [
+    ".github/git-vibe.yml",
+    ".github/workflows/address-feedback.yml",
+    ".github/workflows/develop.yml",
+    ".github/workflows/investigate.yml",
+    ".github/workflows/materialize.yml",
+    ".github/workflows/review.yml",
+    ".github/workflows/validate.yml",
+    ".git-vibe/role-group/correctness.md",
+    ".git-vibe/role-group/maintainability.md",
+    ".git-vibe/role-group/security.md",
+];
+const requiredWorkflowSourcePaths = requiredInstallSourcePaths.filter(isWorkflowSourcePath);
 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,
-        };
-    }));
+    requireSourcePaths(options.sourceFiles, requiredInstallSourcePaths, options.releaseTag);
+    return options.sourceFiles
+        .filter((file) => isInstallSourcePath(file.relativePath))
+        .map((file) => buildInstallFile(file, options.cwd, options.releaseTag));
+}
+export function buildWorkflowUpdateFiles(options) {
+    requireSourcePaths(options.sourceFiles, requiredWorkflowSourcePaths, options.releaseTag);
+    return options.sourceFiles
+        .filter((file) => isWorkflowSourcePath(file.relativePath))
+        .map((file) => buildInstallFile(file, options.cwd, options.releaseTag));
 }
 export function blockingInstallPaths(files) {
     return files
@@ -18,6 +31,12 @@ export function blockingInstallPaths(files) {
         .filter((targetPath) => existsSync(targetPath))
         .sort();
 }
+export function unmanagedWorkflowUpdatePaths(files) {
+    return files
+        .filter((file) => existsSync(file.targetPath) && !isManagedWorkflowTarget(file))
+        .map((file) => file.targetPath)
+        .sort();
+}
 export function installFiles(files) {
     const createdDirectories = [];
     const createdFiles = [];
@@ -33,36 +52,55 @@ export function installFiles(files) {
         throw error;
     }
 }
+export function updateFiles(files) {
+    const createdDirectories = [];
+    const snapshots = [];
+    try {
+        for (const file of files) {
+            ensureDirectory(dirname(file.targetPath), createdDirectories);
+            snapshots.push(snapshotFile(file.targetPath));
+            writeFileSync(file.targetPath, file.content);
+        }
+    }
+    catch (error) {
+        rollbackUpdate(snapshots, 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 unmanagedWorkflowUpdateError(paths, cwd) {
+    const listed = paths.map((path) => `- ${relative(cwd, path) || path}`).join("\n");
+    return new Error(`git-vibe-setup found workflow files that do not look like GitVibe wrappers and did not overwrite them:\n${listed}`);
+}
 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 isManagedWorkflowTarget(file) {
+    try {
+        const workflowName = basename(file.targetPath);
+        return managedWorkflowPattern(workflowName).test(readFileSync(file.targetPath, "utf8"));
+    }
+    catch {
+        return false;
+    }
+}
+function managedWorkflowPattern(workflowName) {
+    return new RegExp(`uses:\\s*markhuangai/git-vibe/\\.github/workflows/${escapeRegExp(workflowName)}@`);
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, String.raw `\$&`);
+}
+function snapshotFile(targetPath) {
+    if (!existsSync(targetPath))
+        return { existed: false, targetPath };
+    return {
+        content: readFileSync(targetPath, "utf8"),
+        existed: true,
+        targetPath,
+    };
 }
 function ensureDirectory(directory, createdDirectories) {
     const missing = missingDirectories(directory);
@@ -84,6 +122,19 @@ function missingDirectories(directory) {
     }
     return missing.reverse();
 }
+function rollbackUpdate(snapshots, createdDirectories) {
+    for (const snapshot of [...snapshots].reverse()) {
+        if (snapshot.existed) {
+            writeFileSync(snapshot.targetPath, snapshot.content || "");
+        }
+        else {
+            rmSync(snapshot.targetPath, { force: true });
+        }
+    }
+    for (const directory of [...createdDirectories].reverse()) {
+        rmSync(directory, { force: true, recursive: false });
+    }
+}
 function rollbackInstall(createdFiles, createdDirectories) {
     for (const file of [...createdFiles].reverse()) {
         rmSync(file, { force: true });
@@ -92,3 +143,34 @@ function rollbackInstall(createdFiles, createdDirectories) {
         rmSync(directory, { force: true, recursive: false });
     }
 }
+function buildInstallFile(sourceFile, cwd, releaseTag) {
+    return {
+        content: pinWorkflowReleaseRefs(sourceFile.content, releaseTag),
+        sourcePath: sourceFile.sourcePath,
+        targetPath: join(cwd, safeRelativePath(sourceFile.relativePath)),
+    };
+}
+function requireSourcePaths(sourceFiles, requiredPaths, releaseTag) {
+    const sourcePaths = new Set(sourceFiles.map((file) => file.relativePath));
+    const missingPaths = requiredPaths.filter((path) => !sourcePaths.has(path));
+    if (missingPaths.length === 0)
+        return;
+    const listed = missingPaths.map((path) => `- examples/consumer/${path}`).join("\n");
+    throw new Error(`git-vibe-setup found an incomplete GitVibe consumer starter at markhuangai/git-vibe@${releaseTag}. Missing files:\n${listed}\nNo files were written.`);
+}
+function isInstallSourcePath(relativePath) {
+    return relativePath.startsWith(".github/") || relativePath.startsWith(".git-vibe/");
+}
+function isWorkflowSourcePath(relativePath) {
+    return relativePath.startsWith(".github/workflows/") && relativePath.endsWith(".yml");
+}
+function safeRelativePath(relativePath) {
+    const segments = relativePath.split("/");
+    const isSafe = relativePath.length > 0 &&
+        !relativePath.startsWith("/") &&
+        !relativePath.includes("\\") &&
+        segments.every((segment) => segment.length > 0 && segment !== "." && segment !== "..");
+    if (isSafe)
+        return relativePath;
+    throw new Error(`git-vibe-setup found an unsafe starter file path: ${relativePath}`);
+}

package/dist/releases.d.ts

@@ -7,5 +7,15 @@ export interface GitHubRelease {
 }
 export declare class ReleaseLookupError extends Error {
 }
+export interface ReleaseLookupOptions {
+    fetchImpl?: typeof fetch;
+    githubToken?: string;
+    includePrereleases?: boolean;
+}
+export interface ReleaseSelectionOptions {
+    includePrereleases?: boolean;
+}
 export declare function latestStableReleaseTag(fetchImpl?: typeof fetch): Promise<string>;
+export declare function latestReleaseTag(options?: ReleaseLookupOptions): Promise<string>;
 export declare function selectLatestStableRelease(releases: GitHubRelease[]): GitHubRelease | undefined;
+export declare function selectLatestRelease(releases: GitHubRelease[], options?: ReleaseSelectionOptions): GitHubRelease | undefined;

package/dist/releases.js

@@ -1,38 +1,42 @@
+import { githubApiHeaders } from "./github-api.js";
 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);
+    return latestReleaseTag({ fetchImpl });
+}
+export async function latestReleaseTag(options = {}) {
+    const releases = await fetchReleases(options.fetchImpl || fetch, options.githubToken);
+    const release = selectLatestRelease(releases, options);
     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.");
+        throw new ReleaseLookupError(`git-vibe-setup could not check the latest GitVibe update because ${missingReleaseReason(options)}. No files were written.`);
     }
     return release.tag_name;
 }
 export function selectLatestStableRelease(releases) {
+    return selectLatestRelease(releases);
+}
+export function selectLatestRelease(releases, options = {}) {
     return releases
-        .filter((release) => !release.draft && !release.prerelease && release.tag_name)
+        .filter((release) => !release.draft && (options.includePrereleases || !release.prerelease) && release.tag_name)
         .sort(compareReleaseFreshness)[0];
 }
-async function fetchReleases(fetchImpl) {
+async function fetchReleases(fetchImpl, githubToken) {
     const releases = [];
     for (let page = 1;; page += 1) {
-        const data = await fetchReleasePage(fetchImpl, page);
+        const data = await fetchReleasePage(fetchImpl, page, githubToken);
         releases.push(...data);
         if (data.length < releasesPerPage)
             return releases;
     }
 }
-async function fetchReleasePage(fetchImpl, page) {
+async function fetchReleasePage(fetchImpl, page, githubToken) {
     let response;
+    const headers = githubApiHeaders(githubToken);
     try {
         response = await fetchImpl(releasePageUrl(page), {
-            headers: {
-                accept: "application/vnd.github+json",
-                "user-agent": "git-vibe-setup",
-                "x-github-api-version": "2022-11-28",
-            },
+            headers,
         });
     }
     catch {
@@ -63,3 +67,8 @@ function releaseTime(release) {
 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.");
 }
+function missingReleaseReason(options) {
+    return options.includePrereleases
+        ? "no stable or prerelease release is available"
+        : "no stable release is available";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "git-vibe-setup",
-  "version": "3.0.2",
+  "version": "3.1.0",
   "private": false,
   "type": "module",
   "bin": {
@@ -8,7 +8,6 @@
   },
   "files": [
     "dist",
-    "templates",
     "README.md"
   ],
   "scripts": {

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

@@ -1,7 +0,0 @@
-# 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

@@ -1,7 +0,0 @@
-# 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

@@ -1,7 +0,0 @@
-# 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

@@ -1,150 +0,0 @@
-# Copy this file to .github/git-vibe.yml in the consumer repository.
-
-version: 1
-
-permissions:
-  # Users with write, maintain, or admin can approve automation.
-  approver_roles:
-    - write
-    - maintain
-    - admin
-
-labels:
-  story: gvi:story
-  needs_discussion: gvi:needs-discussion
-  investigate: git-vibe:investigate
-  investigating: gvi:investigating
-  investigated: gvi:investigated
-  ready_for_approval: gvi:ready-for-approval
-  approved: git-vibe:approved
-  review: git-vibe:review
-  reviewing: gvi:reviewing
-  in_progress: gvi:in-progress
-  blocked: gvi:blocked
-  pr_opened: gvi:pr-opened
-  pr_approved: gvi:pr-approved
-  pr_merged: gvi:pr-merged
-  validate: git-vibe:validate
-  validating: gvi:validating
-  validated: gvi:validated
-
-commands:
-  prefix: /git-vibe
-  allow_external_agent_mentions: false
-
-event_delivery:
-  # webhook: repository webhook points at the self-hosted GitVibe server.
-  # relay: webhook proxy/tunnel such as Smee, Hookdeck, Cloudflare Tunnel, or ngrok.
-  # actions: no-server receiver workflows in the consumer repository.
-  # polling: local/scheduled worker polls GitHub APIs with cursors/ETags.
-  mode: webhook
-  relay:
-    provider: smee
-    # GitHub Actions Secret name. Relay URLs may contain delivery tokens; do not commit the real URL.
-    url_secret: GITVIBE_RELAY_URL
-  actions_receiver:
-    enabled: false
-    scheduled_scan: "*/15 * * * *"
-  polling:
-    enabled: false
-    interval_seconds: 300
-
-github_auth:
-  # Self-hosted default: the GitVibe server uses a fine-grained PAT scoped to this repository.
-  mode: webhook-pat
-  # GitHub Actions Secret name. Stores the GitHub write token.
-  token_secret: GITVIBE_GITHUB_TOKEN
-
-tests:
-  commands: []
-
-ai:
-  security:
-    web:
-      # Default for public repositories: let AI search current GitHub project material only.
-      # Add domains only for websites the repository owner trusts AI to search and fetch.
-      allowed_domains: []
-      # - github.com
-      # - "*.github.com"
-  profiles:
-    local_proxy:
-      adapter: ai-sdk-agentool
-      # Optional: set to the selected model's context window.
-      # context_window_tokens: 128000
-      provider:
-        # openai, anthropic, or openai-compatible.
-        type: openai-compatible
-        # Model names are configuration, not credentials.
-        model: glm-5
-        # Keys inside GITVIBE_AI_ENV_JSON. Store provider credentials and endpoints there.
-        base_url:
-          from_bundle: GITVIBE_AI_BASE_URL
-        api_key:
-          from_bundle: GITVIBE_AI_API_KEY
-      reasoning:
-        effort: high
-      provider_options:
-        openai:
-          reasoningEffort: high
-          reasoningSummary: concise
-        anthropic:
-          effort: high
-    codex_cli:
-      adapter: cli-codex
-      # Key inside GITVIBE_AI_ENV_JSON. Stores escaped auth.json text from jq -Rs .
-      # Requires GITVIBE_GITHUB_TOKEN repository Secrets read/write permission for refresh write-back.
-      auth_json:
-        from_bundle: CODEX_AUTH_JSON
-      model: gpt-5.3-codex
-      reasoning:
-        effort: high
-        summary: concise
-    claude_code:
-      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
-    review_timeout_minutes: 60
-    implementation_timeout_minutes: 120
-    feedback_timeout_minutes: 120
-    create_pr_timeout_minutes: 15
-    default_max_turns: 90
-    implementation_max_turns: 200
-    feedback_max_turns: 120
-    validation_repair_attempts: 3
-    validation_repair_max_turns: 45
-    pr_feedback_max_iterations: 3
-    request_retry_attempts: 3
-    request_retry_delay_seconds: 60
-  stages:
-    investigate:
-      role_group: review_gate
-    validate:
-      role_group: review_gate
-    materialize:
-      profile: local_proxy
-    implement:
-      profile: local_proxy
-    review-matrix:
-      role_group: review_gate
-    create-pr:
-      profile: local_proxy
-    address-pr-feedback:
-      profile: local_proxy

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

@@ -1,34 +0,0 @@
-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@v3
-    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/develop.yml

@@ -1,39 +0,0 @@
-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@v3
-    with:
-      issue-number: ${{ inputs.issue-number }}
-      runner: ubuntu-latest
-      implementation_timeout_minutes: 120
-      review_timeout_minutes: 60
-      create_pr_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

@@ -1,34 +0,0 @@
-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@v3
-    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

@@ -1,34 +0,0 @@
-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@v3
-    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/review.yml

@@ -1,34 +0,0 @@
-name: GitVibe review
-run-name: "[git-vibe][review]: PR #${{ inputs.pr-number }}"
-
-on:
-  workflow_dispatch:
-    inputs:
-      pr-number:
-        description: Pull request number to review.
-        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:
-  review:
-    uses: markhuangai/git-vibe/.github/workflows/review.yml@v3
-    with:
-      pr-number: ${{ inputs.pr-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

@@ -1,41 +0,0 @@
-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@v3
-    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

@@ -1,8 +0,0 @@
-{
-  "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"
-}