@ttfw/envoi 1.0.0

package/dist/lib/git_branching.js

@@ -0,0 +1,327 @@
+/**
+ * Git branching helper functions for runner-owned branch management.
+ *
+ * Uses execSync for git operations to ensure synchronous, blocking behavior.
+ * All git commands use argv-only (no shell strings) for security.
+ */
+import { spawnSync } from 'node:child_process';
+/**
+ * Expands a branch name template with placeholders.
+ *
+ * Supported placeholders (both {{...}} and {...} styles):
+ * - {{task_id}} or {task_id} - Task ID
+ * - {{milestone_id}} or {milestone_id} - Milestone ID
+ * - {{run_id}} or {run_id} - Run ID
+ * - {{tick_count}} or {tick_count} - Tick count (1-based)
+ * - {{seq}} or {seq} or {{batch_index}} or {batch_index} - Sequence/batch index (0-based)
+ * - {{YYYYMMDD}} or {YYYYMMDD} - Date in YYYYMMDD format
+ *
+ * @param template - Template string with placeholders
+ * @param params - Parameters to substitute
+ * @returns Expanded branch name
+ */
+export function expandBranchTemplate(template, params) {
+    let result = template;
+    // Generate YYYYMMDD if not provided
+    if (!params.YYYYMMDD) {
+        const now = new Date();
+        const year = now.getFullYear();
+        const month = String(now.getMonth() + 1).padStart(2, '0');
+        const day = String(now.getDate()).padStart(2, '0');
+        params.YYYYMMDD = `${year}${month}${day}`;
+    }
+    // Use seq if batch_index is provided but seq is not
+    if (params.batch_index !== undefined && params.seq === undefined) {
+        params.seq = params.batch_index;
+    }
+    // Replace both {{...}} and {...} styles
+    const replacements = [
+        [/\{\{task_id\}\}|\{task_id\}/g, params.task_id || ''],
+        [/\{\{milestone_id\}\}|\{milestone_id\}/g, params.milestone_id || ''],
+        [/\{\{run_id\}\}|\{run_id\}/g, params.run_id || ''],
+        [/\{\{tick_count\}\}|\{tick_count\}/g, params.tick_count !== undefined ? String(params.tick_count) : ''],
+        [/\{\{seq\}\}|\{seq\}/g, params.seq !== undefined ? String(params.seq) : ''],
+        [/\{\{batch_index\}\}|\{batch_index\}/g, params.seq !== undefined ? String(params.seq) : ''],
+        [/\{\{YYYYMMDD\}\}|\{YYYYMMDD\}/g, params.YYYYMMDD || ''],
+    ];
+    for (const [pattern, replacement] of replacements) {
+        result = result.replace(pattern, replacement);
+    }
+    // Remove any remaining placeholders (replace with empty string)
+    result = result.replace(/\{\{?\w+\}?\}/g, '');
+    return result;
+}
+/**
+ * Checks if a branch exists locally.
+ *
+ * @param branchName - Branch name to check
+ * @returns true if branch exists, false otherwise
+ */
+function branchExists(branchName) {
+    try {
+        const result = spawnSync('git', ['show-ref', '--verify', '--quiet', `refs/heads/${branchName}`], {
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        return result.status === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Gets the current branch name.
+ *
+ * @returns Current branch name, or null if detached HEAD
+ */
+function getCurrentBranch() {
+    try {
+        const result = spawnSync('git', ['branch', '--show-current'], {
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        if (result.status !== 0 || !result.stdout) {
+            return null;
+        }
+        return result.stdout.toString().trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Creates a new branch or switches to existing branch.
+ *
+ * If the branch already exists, switches to it.
+ * If the branch doesn't exist, creates it from the specified base ref (default: HEAD).
+ *
+ * @param branchName - Branch name to create/switch to
+ * @param baseRef - Base ref (commit/branch) to create branch from. Default: 'HEAD'
+ * @returns BranchResult indicating success or failure
+ */
+function createOrSwitchBranch(branchName, baseRef = 'HEAD') {
+    const exists = branchExists(branchName);
+    const currentBranch = getCurrentBranch();
+    // If already on the target branch, no-op
+    if (currentBranch === branchName) {
+        return {
+            ok: true,
+            branchName,
+            existed: exists,
+        };
+    }
+    try {
+        let result;
+        if (exists) {
+            // Branch exists, switch to it
+            result = spawnSync('git', ['checkout', branchName], {
+                encoding: 'utf-8',
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+        }
+        else {
+            // Branch doesn't exist, create it from baseRef
+            result = spawnSync('git', ['checkout', '-b', branchName, baseRef], {
+                encoding: 'utf-8',
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+        }
+        if (result.status !== 0) {
+            const errorMsg = result.stderr?.toString() || `Git command failed with status ${result.status}`;
+            return {
+                ok: false,
+                branchName,
+                existed: exists,
+                error: errorMsg,
+            };
+        }
+        return {
+            ok: true,
+            branchName,
+            existed: exists,
+        };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            branchName,
+            existed: exists,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+/**
+ * Finds an available branch name by appending a numeric suffix.
+ *
+ * If the base name exists, tries base-1, base-2, etc. until finding an available name.
+ *
+ * @param baseName - Base branch name
+ * @param maxAttempts - Maximum number of attempts (default: 100)
+ * @returns Available branch name
+ */
+function findAvailableBranchName(baseName, maxAttempts = 100) {
+    if (!branchExists(baseName)) {
+        return baseName;
+    }
+    for (let i = 1; i <= maxAttempts; i++) {
+        const candidate = `${baseName}-${i}`;
+        if (!branchExists(candidate)) {
+            return candidate;
+        }
+    }
+    // Fallback: use timestamp if all attempts exhausted
+    return `${baseName}-${Date.now()}`;
+}
+/**
+ * Sanitizes a branch name to comply with git branch naming rules.
+ *
+ * @param name - Branch name to sanitize
+ * @returns Sanitized branch name
+ */
+function sanitizeBranchName(name) {
+    // Replace invalid characters with hyphens
+    let sanitized = name
+        .replace(/[^a-zA-Z0-9\/_\-\.]/g, '-')
+        .replace(/\/+/g, '/')
+        .replace(/^-+|-+$/g, '');
+    // Ensure it's not empty
+    if (!sanitized) {
+        sanitized = 'envoi/branch';
+    }
+    return sanitized;
+}
+/**
+ * Ensures a branch exists and HEAD is on it (per_tick mode).
+ *
+ * For per_tick mode, creates/switches to a branch based on the template.
+ * If the branch already exists, switches to it (idempotent).
+ * If there's a collision, appends a numeric suffix.
+ *
+ * @param config - Git branching configuration
+ * @param params - Parameters for template expansion
+ * @returns BranchResult indicating success or failure
+ */
+export function ensureBranchPerTick(config, params) {
+    if (config.mode !== 'per_tick') {
+        return {
+            ok: false,
+            branchName: '',
+            error: `Branching mode is not 'per_tick' (got '${config.mode}')`,
+            existed: false,
+        };
+    }
+    const template = config.name_template || 'envoi/{{task_id}}';
+    const baseName = expandBranchTemplate(template, params);
+    const sanitizedName = sanitizeBranchName(baseName);
+    if (!sanitizedName) {
+        return {
+            ok: false,
+            branchName: '',
+            error: 'Branch name template expanded to empty string',
+            existed: false,
+        };
+    }
+    // Find available branch name (handles collisions)
+    const branchName = findAvailableBranchName(sanitizedName);
+    const baseRef = config.base_ref || 'HEAD';
+    return createOrSwitchBranch(branchName, baseRef);
+}
+/**
+ * Ensures a branch exists and HEAD is on it (per_n_tasks mode).
+ *
+ * For per_n_tasks mode, creates/switches to a branch based on the template,
+ * grouping tasks into batches of n_tasks. The seq parameter represents
+ * the batch index (0-based).
+ *
+ * @param config - Git branching configuration
+ * @param params - Parameters for template expansion (must include seq for batch index)
+ * @returns BranchResult indicating success or failure
+ */
+export function ensureBranchPerNTasks(config, params) {
+    if (config.mode !== 'per_n_tasks') {
+        return {
+            ok: false,
+            branchName: '',
+            error: `Branching mode is not 'per_n_tasks' (got '${config.mode}')`,
+            existed: false,
+        };
+    }
+    if (!config.n_tasks || config.n_tasks < 1) {
+        return {
+            ok: false,
+            branchName: '',
+            error: `per_n_tasks mode requires n_tasks >= 1 (got ${config.n_tasks})`,
+            existed: false,
+        };
+    }
+    if (params.seq === undefined && params.batch_index === undefined) {
+        return {
+            ok: false,
+            branchName: '',
+            error: 'per_n_tasks mode requires seq or batch_index parameter',
+            existed: false,
+        };
+    }
+    // Use seq if available, otherwise batch_index
+    const batchIndex = params.seq !== undefined ? params.seq : (params.batch_index || 0);
+    const templateParams = { ...params, seq: batchIndex, batch_index: batchIndex };
+    const template = config.name_template || 'envoi/batch-{{seq}}';
+    const baseName = expandBranchTemplate(template, templateParams);
+    const sanitizedName = sanitizeBranchName(baseName);
+    if (!sanitizedName) {
+        return {
+            ok: false,
+            branchName: '',
+            error: 'Branch name template expanded to empty string',
+            existed: false,
+        };
+    }
+    // Find available branch name (handles collisions)
+    const branchName = findAvailableBranchName(sanitizedName);
+    const baseRef = config.base_ref || 'HEAD';
+    return createOrSwitchBranch(branchName, baseRef);
+}
+/**
+ * Ensures a branch exists and HEAD is on it (per_milestone mode).
+ *
+ * For per_milestone mode, creates/switches to a branch based on the template
+ * for the current milestone. All tasks in the same milestone use the same branch.
+ *
+ * @param config - Git branching configuration
+ * @param params - Parameters for template expansion (must include milestone_id)
+ * @returns BranchResult indicating success or failure
+ */
+export function ensureBranchPerMilestone(config, params) {
+    if (config.mode !== 'per_milestone') {
+        return {
+            ok: false,
+            branchName: '',
+            error: `Branching mode is not 'per_milestone' (got '${config.mode}')`,
+            existed: false,
+        };
+    }
+    if (!params.milestone_id) {
+        return {
+            ok: false,
+            branchName: '',
+            error: 'per_milestone mode requires milestone_id parameter',
+            existed: false,
+        };
+    }
+    const template = config.name_template || 'envoi/{{milestone_id}}';
+    const baseName = expandBranchTemplate(template, params);
+    const sanitizedName = sanitizeBranchName(baseName);
+    if (!sanitizedName) {
+        return {
+            ok: false,
+            branchName: '',
+            error: 'Branch name template expanded to empty string',
+            existed: false,
+        };
+    }
+    // Find available branch name (handles collisions)
+    const branchName = findAvailableBranchName(sanitizedName);
+    const baseRef = config.base_ref || 'HEAD';
+    return createOrSwitchBranch(branchName, baseRef);
+}
+//# sourceMappingURL=git_branching.js.map

package/dist/lib/git_branching.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git_branching.js","sourceRoot":"","sources":["../../src/lib/git_branching.ts"],"names":[],"mappings":"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"}

package/dist/lib/gitignore.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Utilities for managing .gitignore entries for Envoi runner-owned files.
+ *
+ * Runner-owned files (STATE.json, REPORT.json, etc.) change every tick and
+ * should be gitignored to prevent BLOCKED_DIRTY_WORKTREE on subsequent runs.
+ */
+/**
+ * Marker comment to identify Envoi-managed section in .gitignore.
+ */
+export declare const ENVOI_GITIGNORE_MARKER = "# Envoi runner-owned (auto-generated)";
+/**
+ * Default entries to add to .gitignore for Envoi runner-owned files.
+ */
+export declare function getEnvoiGitignoreEntries(workspaceDir: string): string[];
+export declare const ENVOI_GITIGNORE_ENTRIES: string[];
+export declare function addEnvoiIgnores(repoRoot: string, entries?: string[]): Promise<{
+    added: string[];
+    alreadyPresent: string[];
+    created: boolean;
+}>;
+export declare function checkEnvoiIgnores(repoRoot: string): Promise<{
+    complete: boolean;
+    missing: string[];
+    present: string[];
+}>;
+//# sourceMappingURL=gitignore.d.ts.map

package/dist/lib/gitignore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gitignore.d.ts","sourceRoot":"","sources":["../../src/lib/gitignore.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH;;GAEG;AACH,eAAO,MAAM,sBAAsB,0CAA0C,CAAC;AAG9E;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,EAAE,CAevE;AAED,eAAO,MAAM,uBAAuB,UAA+C,CAAC;AAWpF,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,MAAM,EAA4B,GAC1C,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,cAAc,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,CA2D1E;AAED,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAmCtE"}

package/dist/lib/gitignore.js

@@ -0,0 +1,119 @@
+/**
+ * Utilities for managing .gitignore entries for Envoi runner-owned files.
+ *
+ * Runner-owned files (STATE.json, REPORT.json, etc.) change every tick and
+ * should be gitignored to prevent BLOCKED_DIRTY_WORKTREE on subsequent runs.
+ */
+import { readFile, writeFile, access } from 'node:fs/promises';
+import { join } from 'node:path';
+import { WORKSPACE_DIR_NAME } from './branding.js';
+/**
+ * Marker comment to identify Envoi-managed section in .gitignore.
+ */
+export const ENVOI_GITIGNORE_MARKER = '# Envoi runner-owned (auto-generated)';
+const MIGRATION_GITIGNORE_MARKER = '# Relais runner-owned (auto-generated)';
+/**
+ * Default entries to add to .gitignore for Envoi runner-owned files.
+ */
+export function getEnvoiGitignoreEntries(workspaceDir) {
+    const ws = workspaceDir.replace(/\/+$/, '');
+    return [
+        `${ws}/REPORT.json`,
+        `${ws}/REPORT.md`,
+        `${ws}/STATE.json`,
+        `${ws}/TASK.json`,
+        `${ws}/BLOCKED.json`,
+        `${ws}/lock.json`,
+        `${ws}/history/`,
+        `${ws}/*.tmp`,
+        `${ws}/PRD.md`,
+        `${ws}/FACTS.md`,
+        `${ws}/BUILDER_RESULT.json`,
+    ];
+}
+export const ENVOI_GITIGNORE_ENTRIES = getEnvoiGitignoreEntries(WORKSPACE_DIR_NAME);
+async function fileExists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function addEnvoiIgnores(repoRoot, entries = ENVOI_GITIGNORE_ENTRIES) {
+    const gitignorePath = join(repoRoot, '.gitignore');
+    let existingContent = '';
+    let created = false;
+    if (await fileExists(gitignorePath)) {
+        existingContent = await readFile(gitignorePath, 'utf-8');
+    }
+    else {
+        created = true;
+    }
+    const existingLines = new Set(existingContent
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0));
+    const hasMarker = existingContent.includes(ENVOI_GITIGNORE_MARKER) ||
+        existingContent.includes(MIGRATION_GITIGNORE_MARKER);
+    const added = [];
+    const alreadyPresent = [];
+    for (const entry of entries) {
+        if (existingLines.has(entry)) {
+            alreadyPresent.push(entry);
+        }
+        else {
+            added.push(entry);
+        }
+    }
+    if (added.length === 0 && hasMarker) {
+        return { added: [], alreadyPresent, created: false };
+    }
+    let newContent = existingContent;
+    if (newContent.length > 0 && !newContent.endsWith('\n')) {
+        newContent += '\n';
+    }
+    if (newContent.length > 0 && !hasMarker) {
+        newContent += '\n';
+    }
+    if (!hasMarker) {
+        newContent += ENVOI_GITIGNORE_MARKER + '\n';
+    }
+    for (const entry of added) {
+        newContent += entry + '\n';
+    }
+    await writeFile(gitignorePath, newContent, 'utf-8');
+    return { added, alreadyPresent, created };
+}
+export async function checkEnvoiIgnores(repoRoot) {
+    const gitignorePath = join(repoRoot, '.gitignore');
+    if (!(await fileExists(gitignorePath))) {
+        return {
+            complete: false,
+            missing: [...ENVOI_GITIGNORE_ENTRIES],
+            present: [],
+        };
+    }
+    const content = await readFile(gitignorePath, 'utf-8');
+    const existingLines = new Set(content
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0));
+    const missing = [];
+    const present = [];
+    for (const entry of ENVOI_GITIGNORE_ENTRIES) {
+        if (existingLines.has(entry)) {
+            present.push(entry);
+        }
+        else {
+            missing.push(entry);
+        }
+    }
+    return {
+        complete: missing.length === 0,
+        missing,
+        present,
+    };
+}
+//# sourceMappingURL=gitignore.js.map

package/dist/lib/gitignore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gitignore.js","sourceRoot":"","sources":["../../src/lib/gitignore.ts"],"names":[],"mappings":"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"}