loopgen 0.1.0

package/dist/core/generator.js

@@ -0,0 +1,226 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { stringify } from "yaml";
+import { generateAgentsFiles } from "../adapters/agents-md.js";
+import { generateClaudeFiles } from "../adapters/claude.js";
+import { generateCodexFiles } from "../adapters/codex.js";
+import { generateCursorFiles } from "../adapters/cursor.js";
+import { generateLocalModelFiles, localModelWarnings } from "../adapters/local-model.js";
+import { generateWindsurfFiles } from "../adapters/windsurf.js";
+import { DEFAULT_ADAPTER_IDS, normalizeAdapterConfigs } from "./adapters.js";
+import { createPreviewDiff } from "./diff.js";
+import { defaultAnswers, createLoopSpec, TEMPLATE_DEFINITIONS, templateIds } from "./templates.js";
+import { scanProject } from "./scanner.js";
+export async function generateLoopProject(options) {
+    const experienceMode = options.experienceMode ?? "project";
+    const projectRoot = resolveProjectRoot(options, experienceMode);
+    const scan = await scanProject(projectRoot);
+    const adapters = options.adapters?.length ? unique(options.adapters) : DEFAULT_ADAPTER_IDS;
+    const adapterConfigs = normalizeAdapterConfigs(options.adapterConfigs);
+    const selectedTemplates = options.selectedTemplates?.length
+        ? unique(options.selectedTemplates)
+        : defaultTemplateSelection(options, experienceMode);
+    const answers = defaultAnswers(scan, {
+        adapters,
+        adapterConfigs,
+        selectedTemplates,
+        triggerCadence: options.triggerCadence ?? "manual",
+        acceptanceCriteria: options.acceptanceCriteria,
+        allowPrCreation: options.allowPrCreation ?? false,
+        allowedCommands: options.allowedCommands?.length ? options.allowedCommands : undefined,
+        maxIterations: options.maxIterations ?? 3
+    });
+    const loops = answers.selectedTemplates.map((id) => createLoopSpec(id, scan, answers));
+    const files = sortFiles([
+        {
+            path: ".loopgen/loopgen.loop.yaml",
+            content: renderLoopYaml(scan.projectName, loops)
+        },
+        {
+            path: ".loopgen/README.md",
+            content: renderLoopgenReadme(scan.projectName)
+        },
+        ...loops.map((loop) => ({
+            path: `.loopgen/playbooks/${loop.id}.md`,
+            content: renderPlaybook(scan.projectName, loop)
+        })),
+        ...loops.map((loop) => ({
+            path: loop.stateFile,
+            content: renderStateFile(loop.id, loop.title)
+        })),
+        ...(answers.adapters.includes("agents-md") ? generateAgentsFiles(scan, loops) : []),
+        ...(answers.adapters.includes("codex") ? generateCodexFiles(scan, loops) : []),
+        ...(answers.adapters.includes("claude") ? generateClaudeFiles(scan, loops) : []),
+        ...(answers.adapters.includes("cursor") ? generateCursorFiles(scan, loops) : []),
+        ...(answers.adapters.includes("windsurf") ? generateWindsurfFiles(scan, loops) : []),
+        ...(answers.adapters.includes("ollama")
+            ? generateLocalModelFiles(scan, loops, { adapterId: "ollama", config: answers.adapterConfigs.ollama ?? {} })
+            : []),
+        ...(answers.adapters.includes("openai-compatible")
+            ? generateLocalModelFiles(scan, loops, {
+                adapterId: "openai-compatible",
+                config: answers.adapterConfigs["openai-compatible"] ?? {}
+            })
+            : [])
+    ]);
+    const warnings = [
+        ...scan.warnings,
+        ...answers.adapters.flatMap((adapter) => localModelWarnings(adapter, answers.adapterConfigs[adapter])),
+        ...loops
+            .filter((loop) => loop.verification.requiresHumanCommandDefinition)
+            .map((loop) => `${loop.id} needs a real verification command before automated execution.`)
+    ];
+    return {
+        experienceMode,
+        scan,
+        loops,
+        files,
+        diff: await createPreviewDiff(scan.root, files),
+        warnings
+    };
+}
+export function demoProjectRoot() {
+    const currentDir = path.dirname(fileURLToPath(import.meta.url));
+    return path.resolve(currentDir, "..", "..", "examples", "demo-webapp");
+}
+function resolveProjectRoot(options, experienceMode) {
+    if (experienceMode === "demo") {
+        return demoProjectRoot();
+    }
+    return path.resolve(options.projectRoot ?? ".");
+}
+function defaultTemplateSelection(options, experienceMode) {
+    const templates = filterTemplateDefinitions(options);
+    if (experienceMode === "demo") {
+        const demoRecommended = templates.filter((template) => template.demoAvailable && template.recommendedForDemo);
+        if (demoRecommended.length > 0)
+            return demoRecommended.map((template) => template.id);
+        return templates.filter((template) => template.demoAvailable).map((template) => template.id);
+    }
+    return templates.length ? templates.map((template) => template.id) : templateIds();
+}
+function filterTemplateDefinitions(options) {
+    return TEMPLATE_DEFINITIONS.filter((template) => {
+        const audienceMatches = !options.audienceFilter || template.audience.includes(options.audienceFilter);
+        const categoryMatches = !options.categoryFilter || template.category === options.categoryFilter;
+        return audienceMatches && categoryMatches;
+    });
+}
+function renderLoopYaml(projectName, loops) {
+    return stringify({
+        version: "0.1",
+        project: projectName,
+        generatedBy: "loopgen",
+        generatedAt: new Date().toISOString(),
+        loops
+    }, { lineWidth: 110 });
+}
+function renderLoopgenReadme(projectName) {
+    return `# loopgen for ${projectName}
+
+This directory contains local-first loop engineering configuration generated by loopgen.
+
+Start with \`.loopgen/loopgen.loop.yaml\`, then read the matching \`.loopgen/playbooks/*.md\` file.
+If you use Codex or Claude, use the generated skill or loop guide that matches the same loop id.
+
+Safety defaults:
+
+- Preview diffs before applying changes.
+- Keep maker and checker work separate.
+- Stop after the configured maximum iterations.
+- Do not read production secrets or forbidden paths.
+- Do not declare success without verification output.
+`;
+}
+function renderPlaybook(projectName, loop) {
+    return `# ${loop.title} playbook
+
+Project: ${projectName}
+Loop id: ${loop.id}
+Category: ${loop.category}
+Audience: ${loop.audience.join(", ")}
+Difficulty: ${loop.difficulty}
+
+## Goal
+
+${loop.goal}
+
+Expected outcome: ${loop.expectedOutcome}
+
+## When to run
+
+- Trigger type: ${loop.trigger.type}
+- Cadence: ${loop.trigger.cadence}
+- Sources: ${loop.trigger.sources.join(", ")}
+
+## Context to gather
+
+${loop.contextSources.map((source) => `- ${source}`).join("\n")}
+
+## Loop steps
+
+${loop.actions.map((action, index) => `${index + 1}. ${action}`).join("\n")}
+
+## Verification
+
+Run these commands before declaring success:
+
+${loop.verification.commands.map((command) => `- \`${command}\``).join("\n")}
+
+Acceptance criteria: ${loop.verification.acceptanceCriteria}
+
+## Safety and state
+
+- State file: \`${loop.stateFile}\`
+- Maximum iterations: ${loop.stopCriteria.maxIterations}
+- Timeout minutes: ${loop.stopCriteria.timeoutMinutes}
+- Maker/checker separation required: ${loop.verification.makerChecker ? "yes" : "no"}
+- Network allowed: ${loop.permissions.allowNetwork ? "yes" : "no"}
+- PR creation allowed: ${loop.permissions.allowPrCreation ? "yes" : "no"}
+- Do not read or modify: ${loop.permissions.forbiddenPaths.map((item) => `\`${item}\``).join(", ")}
+
+Stop and ask for human input when:
+
+${loop.stopCriteria.requireHumanInputOn.map((condition) => `- ${condition}`).join("\n")}
+${loop.verification.requiresHumanCommandDefinition ? "\nThis playbook is in draft mode until the TODO verification command is replaced.\n" : ""}
+`;
+}
+function renderStateFile(id, title) {
+    return `# ${title} state
+
+Loop id: ${id}
+
+## Attempts
+
+- No attempts yet.
+`;
+}
+function sortFiles(files) {
+    return files.sort((a, b) => fileSortKey(a.path).localeCompare(fileSortKey(b.path)));
+}
+function fileSortKey(filePath) {
+    if (filePath.startsWith(".loopgen/playbooks/"))
+        return `0:${filePath}`;
+    if (filePath.startsWith(".loopgen/adapters/"))
+        return `1:${filePath}`;
+    if (filePath === ".loopgen/README.md")
+        return `2:${filePath}`;
+    if (filePath === ".loopgen/loopgen.loop.yaml")
+        return `3:${filePath}`;
+    if (filePath.startsWith(".loopgen/state/"))
+        return `4:${filePath}`;
+    if (filePath.startsWith(".codex/"))
+        return `5:${filePath}`;
+    if (filePath.startsWith(".claude/"))
+        return `6:${filePath}`;
+    if (filePath === "AGENTS.md")
+        return `7:${filePath}`;
+    if (filePath.startsWith(".cursor/"))
+        return `8:${filePath}`;
+    if (filePath === ".windsurfrules")
+        return `9:${filePath}`;
+    return `10:${filePath}`;
+}
+function unique(items) {
+    return [...new Set(items)];
+}

package/dist/core/scanner.js

@@ -0,0 +1,304 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+const IGNORED_DIRS = new Set([
+    ".git",
+    "node_modules",
+    "dist",
+    "dist-web",
+    "build",
+    "coverage",
+    ".cache",
+    ".next",
+    "target",
+    "__pycache__"
+]);
+const SOURCE_EXTENSIONS = new Set([
+    ".ts",
+    ".tsx",
+    ".js",
+    ".jsx",
+    ".mjs",
+    ".cjs",
+    ".py",
+    ".go",
+    ".rs",
+    ".java",
+    ".kt",
+    ".swift",
+    ".rb",
+    ".php",
+    ".cs"
+]);
+const CONFIG_EXTENSIONS = new Set([".json", ".yaml", ".yml", ".toml", ".ini"]);
+export async function scanProject(projectRoot) {
+    const root = path.resolve(projectRoot);
+    const warnings = [];
+    await assertDirectory(root);
+    const packageJson = await readJson(path.join(root, "package.json"));
+    const scripts = readPackageScripts(packageJson);
+    const packageManagers = await detectPackageManagers(root);
+    const languages = await detectLanguages(root);
+    const workflowFiles = await findWorkflowFiles(root);
+    const files = await countProjectFiles(root);
+    const contextSources = await detectContextSources(root, workflowFiles);
+    const commands = inferCommands(root, scripts, packageManagers);
+    if (!commands.test && !commands.lint && !commands.build) {
+        warnings.push("No verification command was inferred. Generated loops will stay in draft mode until one is configured.");
+    }
+    return {
+        root,
+        projectName: packageJson?.name ? String(packageJson.name) : path.basename(root),
+        detectedAt: new Date().toISOString(),
+        languages,
+        primaryLanguage: languages[0] ?? "Unknown",
+        packageManagers,
+        commands,
+        scripts,
+        ci: {
+            providers: workflowFiles.length > 0 ? ["github-actions"] : [],
+            workflowFiles: workflowFiles.map((file) => path.relative(root, file))
+        },
+        files,
+        contextSources,
+        warnings
+    };
+}
+async function assertDirectory(root) {
+    const stat = await fs.stat(root).catch(() => undefined);
+    if (!stat?.isDirectory()) {
+        throw new Error(`Project path is not a directory: ${root}`);
+    }
+}
+async function readJson(filePath) {
+    try {
+        return JSON.parse(await fs.readFile(filePath, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+function readPackageScripts(packageJson) {
+    if (!packageJson || typeof packageJson.scripts !== "object" || !packageJson.scripts) {
+        return {};
+    }
+    return Object.fromEntries(Object.entries(packageJson.scripts).filter(([, value]) => typeof value === "string"));
+}
+async function detectPackageManagers(root) {
+    const checks = [
+        ["pnpm-lock.yaml", "pnpm"],
+        ["package-lock.json", "npm"],
+        ["yarn.lock", "yarn"],
+        ["bun.lockb", "bun"],
+        ["bun.lock", "bun"],
+        ["poetry.lock", "poetry"],
+        ["uv.lock", "uv"],
+        ["go.mod", "go"],
+        ["Cargo.toml", "cargo"]
+    ];
+    const found = [];
+    for (const [file, manager] of checks) {
+        if (await exists(path.join(root, file))) {
+            found.push(manager);
+        }
+    }
+    if ((await exists(path.join(root, "package.json"))) && !found.some((manager) => ["pnpm", "npm", "yarn", "bun"].includes(manager))) {
+        found.push("npm");
+    }
+    if ((await exists(path.join(root, "pyproject.toml"))) && !found.includes("poetry") && !found.includes("uv")) {
+        found.push("python");
+    }
+    if ((await exists(path.join(root, "requirements.txt"))) && !found.includes("python")) {
+        found.push("python");
+    }
+    return found;
+}
+async function detectLanguages(root) {
+    const counts = new Map();
+    await walk(root, async (file) => {
+        const ext = path.extname(file);
+        const language = languageForExtension(ext);
+        if (language) {
+            counts.set(language, (counts.get(language) ?? 0) + 1);
+        }
+    });
+    return [...counts.entries()].sort((a, b) => b[1] - a[1]).map(([language]) => language);
+}
+function languageForExtension(ext) {
+    const map = {
+        ".ts": "TypeScript",
+        ".tsx": "TypeScript",
+        ".js": "JavaScript",
+        ".jsx": "JavaScript",
+        ".mjs": "JavaScript",
+        ".cjs": "JavaScript",
+        ".py": "Python",
+        ".go": "Go",
+        ".rs": "Rust",
+        ".java": "Java",
+        ".kt": "Kotlin",
+        ".swift": "Swift",
+        ".rb": "Ruby",
+        ".php": "PHP",
+        ".cs": "C#"
+    };
+    return map[ext];
+}
+async function findWorkflowFiles(root) {
+    const workflowsDir = path.join(root, ".github", "workflows");
+    const files = [];
+    if (await exists(workflowsDir)) {
+        await walk(workflowsDir, async (file) => {
+            if ([".yml", ".yaml"].includes(path.extname(file))) {
+                files.push(file);
+            }
+        });
+    }
+    if (await exists(path.join(root, ".gitlab-ci.yml"))) {
+        files.push(path.join(root, ".gitlab-ci.yml"));
+    }
+    return files.sort();
+}
+async function countProjectFiles(root) {
+    const counts = {
+        total: 0,
+        source: 0,
+        tests: 0,
+        configs: 0
+    };
+    await walk(root, async (file) => {
+        counts.total += 1;
+        const ext = path.extname(file);
+        const normalized = path.relative(root, file).split(path.sep).join("/");
+        if (SOURCE_EXTENSIONS.has(ext)) {
+            counts.source += 1;
+        }
+        if (/(\btests?\b|\.test\.|\.spec\.|__tests__)/i.test(normalized)) {
+            counts.tests += 1;
+        }
+        if (CONFIG_EXTENSIONS.has(ext) || /(^|\/)(Makefile|Dockerfile|compose\.ya?ml)$/i.test(normalized)) {
+            counts.configs += 1;
+        }
+    });
+    return counts;
+}
+async function detectContextSources(root, workflowFiles) {
+    const candidates = [
+        "README.md",
+        "package.json",
+        "pyproject.toml",
+        "requirements.txt",
+        "go.mod",
+        "Cargo.toml",
+        "Makefile",
+        ...workflowFiles.map((file) => path.relative(root, file))
+    ];
+    const found = [];
+    for (const candidate of candidates) {
+        if (await exists(path.join(root, candidate))) {
+            found.push(candidate);
+        }
+    }
+    return found;
+}
+function inferCommands(root, scripts, managers) {
+    const commands = {};
+    const nodeManager = managers.find((manager) => ["pnpm", "npm", "yarn", "bun"].includes(manager));
+    if (nodeManager) {
+        commands.packageManager = nodeManager;
+        commands.install = installCommandFor(nodeManager);
+        if (scripts.test)
+            commands.test = runScriptCommand(nodeManager, "test");
+        if (scripts.lint)
+            commands.lint = runScriptCommand(nodeManager, "lint");
+        if (scripts.build)
+            commands.build = runScriptCommand(nodeManager, "build");
+        if (scripts.format)
+            commands.format = runScriptCommand(nodeManager, "format");
+        return commands;
+    }
+    if (managers.includes("go")) {
+        commands.packageManager = "go";
+        commands.test = "go test ./...";
+        commands.build = "go build ./...";
+        return commands;
+    }
+    if (managers.includes("cargo")) {
+        commands.packageManager = "cargo";
+        commands.test = "cargo test";
+        commands.build = "cargo build";
+        return commands;
+    }
+    if (managers.includes("poetry")) {
+        commands.packageManager = "poetry";
+        commands.install = "poetry install";
+        commands.test = "poetry run pytest";
+        return commands;
+    }
+    if (managers.includes("uv")) {
+        commands.packageManager = "uv";
+        commands.install = "uv sync";
+        commands.test = "uv run pytest";
+        return commands;
+    }
+    if (managers.includes("python")) {
+        commands.packageManager = "python";
+        commands.install = "python -m pip install -r requirements.txt";
+        commands.test = "python -m pytest";
+    }
+    if (commands.install && !fileLikelyExists(root, "requirements.txt")) {
+        delete commands.install;
+    }
+    return commands;
+}
+function installCommandFor(manager) {
+    if (manager === "pnpm")
+        return "pnpm install --frozen-lockfile";
+    if (manager === "yarn")
+        return "yarn install --frozen-lockfile";
+    if (manager === "bun")
+        return "bun install --frozen-lockfile";
+    return "npm ci";
+}
+function runScriptCommand(manager, script) {
+    if (manager === "npm")
+        return `npm run ${script}`;
+    if (manager === "yarn")
+        return `yarn ${script}`;
+    if (manager === "bun")
+        return `bun run ${script}`;
+    return `pnpm ${script}`;
+}
+function fileLikelyExists(root, file) {
+    return root.length > 0 && file.length > 0;
+}
+async function exists(filePath) {
+    try {
+        await fs.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function walk(root, onFile) {
+    const queue = [root];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        const entries = await fs.readdir(current, { withFileTypes: true }).catch(() => []);
+        for (const entry of entries) {
+            if (entry.name.startsWith(".") && entry.name !== ".github" && entry.name !== ".gitlab-ci.yml") {
+                if (entry.name !== ".github")
+                    continue;
+            }
+            const fullPath = path.join(current, entry.name);
+            if (entry.isDirectory()) {
+                if (!IGNORED_DIRS.has(entry.name)) {
+                    queue.push(fullPath);
+                }
+            }
+            else if (entry.isFile()) {
+                await onFile(fullPath);
+            }
+        }
+    }
+}