glm-coding-router 0.2.0 → 0.3.0

package/dist/commands/delegate.js

@@ -0,0 +1,134 @@
+import os from "node:os";
+import { loadConfig } from "../core/config.js";
+import { locateClaude } from "../core/claude.js";
+import { createGlmEnv } from "../core/env.js";
+import { Errors } from "../core/errors.js";
+import { gitTopLevel } from "../core/git.js";
+import { logger, redact } from "../core/logging.js";
+import { spawnAgent } from "../core/process.js";
+import { applyProfile } from "../core/profile.js";
+import { readStdin, resolvePrompt } from "../core/prompt.js";
+import { resolveZaiApiKey } from "../core/zai-key.js";
+import { createDelegateWorktree, delegateBranch, delegateWorktreePath, removeDelegateWorktree, rollbackDelegateBranch, validateDelegateName, } from "../core/worktree.js";
+import { buildWorkerArgs } from "../bin/glm-worker.js";
+import { emitJson } from "./context.js";
+/** A profile literally named after the delegate applies unless --profile says otherwise. */
+function resolveProfileName(name, options, config) {
+    if (options.profile) {
+        return options.profile;
+    }
+    return config.profiles[name] ? name : undefined;
+}
+function banner(text, quiet) {
+    if (!quiet) {
+        process.stdout.write(`${text}\n`);
+    }
+}
+/**
+ * glm-router delegate (spec §54 v0.3, specs/delegate-worktrees.md): run a GLM
+ * worker in an isolated git worktree. Worktree + branch are kept after the run
+ * (no automatic git commits); --remove drops the worktree after success only.
+ */
+export async function delegateCommand(name, promptArgs, options, deps = {}) {
+    validateDelegateName(name);
+    const cwd = deps.cwd ?? process.cwd();
+    const env = deps.env ?? process.env;
+    const runGit = deps.runGit;
+    const repoRoot = await gitTopLevel(cwd, runGit);
+    if (!repoRoot) {
+        throw Errors.gitRepoRequired(cwd);
+    }
+    const home = deps.home ?? os.homedir();
+    const baseConfig = loadConfig(home);
+    const profileName = resolveProfileName(name, options, baseConfig);
+    const config = applyProfile(baseConfig, profileName);
+    const resolved = resolveZaiApiKey({ env, readUserEnv: deps.readUserEnv });
+    if (!resolved) {
+        throw Errors.zaiKeyMissing();
+    }
+    const claudePath = locateClaude(config, env);
+    const prompt = await resolvePrompt(promptArgs, deps.readStdinFn ?? readStdin, "glm-router delegate");
+    const branch = delegateBranch(name);
+    const worktreePath = delegateWorktreePath(repoRoot, name);
+    if (options.dryRun) {
+        if (options.json) {
+            emitJson({ name, profile: profileName ?? null, worktree: worktreePath, branch, dryRun: true });
+        }
+        else {
+            banner(`would create worktree ${worktreePath}`, options.quiet);
+            banner(`would create branch   ${branch} (from HEAD)`, options.quiet);
+            banner(`would run glm-worker in the worktree with the given prompt`, options.quiet);
+        }
+        return 0;
+    }
+    // Collision checks run inside createDelegateWorktree before anything is written.
+    const createdPath = await createDelegateWorktree(repoRoot, name, { runGit });
+    if (options.json) {
+        emitJson({ name, profile: profileName ?? null, worktree: createdPath, branch });
+    }
+    else {
+        banner(`[glm-router] delegate ${name}`, options.quiet);
+        banner(`[glm-router] worktree ${createdPath}`, options.quiet);
+        banner(`[glm-router] branch   ${branch}`, options.quiet);
+        if (profileName) {
+            banner(`[glm-router] profile  ${profileName}`, options.quiet);
+        }
+    }
+    const args = buildWorkerArgs(prompt, config);
+    const childEnv = createGlmEnv(config, resolved.key, env);
+    logger.debug(redact(`spawning ${claudePath} in ${createdPath}`, [resolved.key]));
+    const spawn = deps.spawn ?? ((binPath, spawnOptions) => spawnAgent(binPath, {
+        args: [...spawnOptions.args],
+        cwd: spawnOptions.cwd,
+        env: spawnOptions.env,
+        interactive: false,
+    }));
+    let exitCode;
+    try {
+        exitCode = await spawn(claudePath, { args, cwd: createdPath, env: childEnv, interactive: false });
+    }
+    catch (error) {
+        // Worker never started: roll back the pristine worktree and its branch so
+        // the same delegate name can simply be re-run.
+        const worktreeComplaint = await removeDelegateWorktree(repoRoot, createdPath, { runGit });
+        if (worktreeComplaint) {
+            logger.debug(`worktree kept after spawn failure: ${worktreeComplaint}`);
+        }
+        const branchComplaint = await rollbackDelegateBranch(repoRoot, branch, { runGit });
+        if (branchComplaint) {
+            logger.debug(`branch kept after spawn failure: ${branchComplaint}`);
+        }
+        throw error;
+    }
+    let removed = false;
+    if (options.remove && exitCode === 0) {
+        const complaint = await removeDelegateWorktree(repoRoot, createdPath, { runGit });
+        if (complaint) {
+            removed = false;
+            const message = `git refused to remove the worktree (it may contain uncommitted work):\n  ${complaint.trim().split("\n").join("\n  ")}`;
+            if (options.json) {
+                emitJson({ name, exitCode, worktree: createdPath, branch, removed: false, note: message });
+            }
+            else {
+                banner(`[glm-router] ${message}`, options.quiet);
+                banner(`[glm-router] worktree kept at ${createdPath}`, options.quiet);
+            }
+            return exitCode;
+        }
+        removed = true;
+    }
+    if (options.json) {
+        emitJson({ name, exitCode, worktree: createdPath, branch, removed });
+    }
+    else {
+        banner(`[glm-router] worker exited ${exitCode}`, options.quiet);
+        if (removed) {
+            banner(`[glm-router] worktree removed; branch ${branch} kept`, options.quiet);
+        }
+        else {
+            banner(`[glm-router] worktree kept at ${createdPath}`, options.quiet);
+            banner(`[glm-router] next: inspect it, then merge ${branch} (or discard with git worktree remove)`, options.quiet);
+        }
+    }
+    return exitCode;
+}

package/dist/core/errors.js

@@ -96,6 +96,30 @@ export const Errors = {
         ],
         exitCode: ExitCode.InvalidArgs,
     }),
+    gitNotFound: () => new GlmRouterError({
+        name: "GIT_NOT_FOUND",
+        message: "git was not found on PATH.",
+        hint: ["delegate needs git for worktree isolation.", "", "Install Git for Windows: https://git-scm.com/download/win"],
+        exitCode: ExitCode.ProjectRootNotFound,
+    }),
+    gitRepoRequired: (cwd) => new GlmRouterError({
+        name: "GIT_REPO_REQUIRED",
+        message: `Not inside a git repository (cwd: ${cwd}).`,
+        hint: ["delegate runs each worker in a git worktree and needs a repo root.", "", "Run it from inside the project's git repository, or create one:", "", "  git init"],
+        exitCode: ExitCode.ProjectRootNotFound,
+    }),
+    worktreeFailed: (operation, cause, hint) => new GlmRouterError({
+        name: "WORKTREE_FAILED",
+        message: `git ${operation} failed: ${cause.trim() || "unknown git error"}`,
+        hint: hint ?? ["Fix the state git describes above, then re-run the delegate command."],
+        exitCode: ExitCode.ManagedFileWriteFailed,
+    }),
+    invalidDelegateName: (name) => new GlmRouterError({
+        name: "INVALID_DELEGATE_NAME",
+        message: `"${name}" is not a valid delegate name.`,
+        hint: ["Use letters, digits, dots, dashes, underscores; start with a letter or digit.", "", "Examples: backend, auth-refresh, tests.v2"],
+        exitCode: ExitCode.InvalidArgs,
+    }),
     managedBlockCorrupt: (file, cause) => new GlmRouterError({
         name: "MANAGED_BLOCK_CORRUPT",
         message: `Managed block in ${file} is malformed: ${cause}`,

package/dist/core/git.js

@@ -0,0 +1,31 @@
+import { execFile } from "node:child_process";
+import path from "node:path";
+import { Errors } from "./errors.js";
+function isENOENT(error) {
+    return error !== null && typeof error === "object" && error.code === "ENOENT";
+}
+/** Real git runner: resolves with the exit code instead of throwing on failure. */
+export const runGit = (args, cwd) => new Promise((resolve, reject) => {
+    execFile("git", args, { cwd, windowsHide: true, encoding: "utf8", maxBuffer: 16 * 1024 * 1024 }, (error, stdout, stderr) => {
+        if (error && isENOENT(error)) {
+            reject(Errors.gitNotFound());
+            return;
+        }
+        const code = error && typeof error.code === "number"
+            ? error.code
+            : 0;
+        resolve({ code, stdout: stdout ?? "", stderr: stderr ?? "" });
+    });
+});
+/**
+ * Strict repo-root lookup for delegate (specs/delegate-worktrees.md):
+ * unlike findProjectRoot, undefined when cwd is not inside a git repo.
+ */
+export async function gitTopLevel(cwd, run = runGit) {
+    const result = await run(["rev-parse", "--show-toplevel"], cwd);
+    if (result.code !== 0) {
+        return undefined;
+    }
+    const root = result.stdout.trim();
+    return root.length > 0 ? path.resolve(root) : undefined;
+}

package/dist/core/worktree.js

@@ -0,0 +1,118 @@
+import fs from "node:fs";
+import path from "node:path";
+import { runGit } from "./git.js";
+import { Errors } from "./errors.js";
+import { logger } from "./logging.js";
+/** Branch prefix for delegate worktrees (specs/delegate-worktrees.md). */
+export const DELEGATE_BRANCH_PREFIX = "glm/delegate/";
+/** Valid delegate slugs: no path separators, spaces, or leading dash (specs/delegate-worktrees.md). */
+export function validateDelegateName(name) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name) || name === "." || name === ".." || name.toLowerCase() === ".git") {
+        throw Errors.invalidDelegateName(name);
+    }
+}
+export function delegateBranch(name) {
+    return `${DELEGATE_BRANCH_PREFIX}${name}`;
+}
+/**
+ * Worktrees live outside the repo so the main checkout's status stays clean
+ * and no .gitignore edit is ever needed: <parent-of-root>/<repo>.glm-worktrees/<name>
+ */
+export function worktreeBaseDir(repoRoot) {
+    return path.join(path.dirname(repoRoot), `${path.basename(repoRoot)}.glm-worktrees`);
+}
+export function delegateWorktreePath(repoRoot, name) {
+    return path.join(worktreeBaseDir(repoRoot), name);
+}
+function ok(result) {
+    return result.code === 0;
+}
+/** True when a local branch already exists (rev-parse --verify --quiet). */
+export async function branchExists(repoRoot, branch, deps = {}) {
+    const run = deps.runGit ?? runGit;
+    const result = await run(["rev-parse", "--verify", "--quiet", `refs/heads/${branch}`], repoRoot);
+    return ok(result);
+}
+/** True when HEAD resolves (the repo has at least one commit). */
+export async function headIsBorn(repoRoot, deps = {}) {
+    const run = deps.runGit ?? runGit;
+    const result = await run(["rev-parse", "--verify", "--quiet", "HEAD"], repoRoot);
+    return ok(result);
+}
+/**
+ * Pre-flight collision checks shared by the real run and --dry-run
+ * (specs/delegate-worktrees.md): fail before creating anything.
+ */
+export async function assertWorktreeAvailable(repoRoot, name, deps = {}) {
+    const existsSync = deps.existsSync ?? fs.existsSync;
+    const branch = delegateBranch(name);
+    const worktreePath = delegateWorktreePath(repoRoot, name);
+    if (await branchExists(repoRoot, branch, deps)) {
+        throw Errors.worktreeFailed("branch", `branch ${branch} already exists`, [
+            "Inspect or merge it first:",
+            "",
+            `  git log ${branch}`,
+            `  git merge ${branch}`,
+            "",
+            `or delete it if it is unwanted:`,
+            "",
+            `  git branch -D ${branch}`,
+        ]);
+    }
+    if (existsSync(worktreePath)) {
+        throw Errors.worktreeFailed("worktree add", `path already exists: ${worktreePath}`, [
+            "A previous worktree directory is in the way:",
+            "",
+            `  ${worktreePath}`,
+            "",
+            "Remove it (or run `git worktree prune`) and re-run the delegate command.",
+        ]);
+    }
+    if (!(await headIsBorn(repoRoot, deps))) {
+        throw Errors.worktreeFailed("worktree add", "HEAD does not point at a commit (repository has no commits yet)", [
+            "delegate creates the worktree from HEAD, so the repository needs at least one commit first:",
+            "",
+            "  git add -A && git commit -m \"initial commit\"",
+        ]);
+    }
+    return worktreePath;
+}
+/** Create the delegate worktree + branch from HEAD. Returns the worktree path. */
+export async function createDelegateWorktree(repoRoot, name, deps = {}) {
+    const run = deps.runGit ?? runGit;
+    const worktreePath = await assertWorktreeAvailable(repoRoot, name, deps);
+    const branch = delegateBranch(name);
+    logger.debug(`git worktree add -b ${branch} ${worktreePath}`);
+    const result = await run(["worktree", "add", "-b", branch, worktreePath], repoRoot);
+    if (!ok(result)) {
+        throw Errors.worktreeFailed("worktree add", result.stderr || result.stdout, ["The worktree was not created; the repository was left as it was."]);
+    }
+    return worktreePath;
+}
+/**
+ * Remove a delegate worktree with plain `git worktree remove` — git refuses
+ * on dirty/untracked trees, which is exactly the safety we want
+ * (specs/delegate-worktrees.md, `--remove`). Never touches the branch.
+ * Returns undefined when removal succeeded, or git's complaint when not.
+ */
+export async function removeDelegateWorktree(repoRoot, worktreePath, deps = {}) {
+    const run = deps.runGit ?? runGit;
+    const result = await run(["worktree", "remove", worktreePath], repoRoot);
+    if (ok(result)) {
+        return undefined;
+    }
+    return result.stderr || result.stdout || "git worktree remove failed";
+}
+/**
+ * Delete a branch this invocation created and never advanced (worker never
+ * started). Only ever called on the spawn-failure rollback path, where the
+ * branch provably sits at HEAD — never on branches a worker may have moved.
+ */
+export async function rollbackDelegateBranch(repoRoot, branch, deps = {}) {
+    const run = deps.runGit ?? runGit;
+    const result = await run(["branch", "-D", branch], repoRoot);
+    if (ok(result)) {
+        return undefined;
+    }
+    return result.stderr || result.stdout || "git branch -D failed";
+}

package/dist/templates/agents-block.js

@@ -1,46 +1,46 @@
 /** Managed block content for AGENTS.md (spec §24). Keep in sync with the spec. */
-export const AGENTS_MANAGED_BLOCK = `<!-- glm-coding-router:start -->
-
-## GLM Worker Delegation
-
-Available commands:
-
-- \`glm-worker "<task>"\`
-- \`glm-review "<task>"\`
-
-Codex is the primary orchestrator.
-
-Delegate:
-- CRUD
-- boilerplate
-- tests
-- documentation
-- mechanical refactoring
-- repository exploration
-- straightforward implementation
-
-Keep in Codex:
-- requirements
-- planning
-- architecture
-- ambiguous business logic
-- complex debugging
-- security decisions
-- integration
-- final review
-
-Before delegation create a task packet:
-
-TASK
-SCOPE
-FILES ALLOWED TO MODIFY
-FILES NOT TO MODIFY
-REQUIREMENTS
-CONSTRAINTS
-ACCEPTANCE CRITERIA
-VALIDATION
-EXPECTED OUTPUT
-
-Never trust a worker's success report without inspecting the resulting changes.
-
+export const AGENTS_MANAGED_BLOCK = `<!-- glm-coding-router:start -->
+
+## GLM Worker Delegation
+
+Available commands:
+
+- \`glm-worker "<task>"\`
+- \`glm-review "<task>"\`
+
+Codex is the primary orchestrator.
+
+Delegate:
+- CRUD
+- boilerplate
+- tests
+- documentation
+- mechanical refactoring
+- repository exploration
+- straightforward implementation
+
+Keep in Codex:
+- requirements
+- planning
+- architecture
+- ambiguous business logic
+- complex debugging
+- security decisions
+- integration
+- final review
+
+Before delegation create a task packet:
+
+TASK
+SCOPE
+FILES ALLOWED TO MODIFY
+FILES NOT TO MODIFY
+REQUIREMENTS
+CONSTRAINTS
+ACCEPTANCE CRITERIA
+VALIDATION
+EXPECTED OUTPUT
+
+Never trust a worker's success report without inspecting the resulting changes.
+
 <!-- glm-coding-router:end -->`;

package/dist/templates/claude-block.js

@@ -1,49 +1,49 @@
 /** Managed block content for CLAUDE.md (spec §20). Keep in sync with the spec. */
-export const CLAUDE_MANAGED_BLOCK = `<!-- glm-coding-router:start -->
-
-## GLM Worker Delegation
-
-GLM workers available:
-
-- \`glm-worker "<task>"\`
-- \`glm-review "<task>"\`
-
-Delegate well-scoped, implementation-heavy work to GLM.
-
-Use GLM for:
-- repository exploration
-- CRUD
-- boilerplate
-- tests
-- documentation
-- mechanical refactoring
-- straightforward implementation
-
-Claude remains responsible for:
-- requirements
-- architecture
-- ambiguous business rules
-- security-sensitive decisions
-- complex debugging
-- integration
-- final review
-
-Before delegation, define:
-- task
-- scope
-- allowed files
-- forbidden files
-- requirements
-- constraints
-- acceptance criteria
-- validation command
-- expected output
-
-After worker completion:
-1. inspect the actual diff
-2. validate against requirements
-3. run relevant tests
-4. resolve integration problems
-5. accept only after verification
-
+export const CLAUDE_MANAGED_BLOCK = `<!-- glm-coding-router:start -->
+
+## GLM Worker Delegation
+
+GLM workers available:
+
+- \`glm-worker "<task>"\`
+- \`glm-review "<task>"\`
+
+Delegate well-scoped, implementation-heavy work to GLM.
+
+Use GLM for:
+- repository exploration
+- CRUD
+- boilerplate
+- tests
+- documentation
+- mechanical refactoring
+- straightforward implementation
+
+Claude remains responsible for:
+- requirements
+- architecture
+- ambiguous business rules
+- security-sensitive decisions
+- complex debugging
+- integration
+- final review
+
+Before delegation, define:
+- task
+- scope
+- allowed files
+- forbidden files
+- requirements
+- constraints
+- acceptance criteria
+- validation command
+- expected output
+
+After worker completion:
+1. inspect the actual diff
+2. validate against requirements
+3. run relevant tests
+4. resolve integration problems
+5. accept only after verification
+
 <!-- glm-coding-router:end -->`;

package/dist/templates/glm-delegation-skill.js

@@ -1,68 +1,68 @@
 /** Codex skill definition (spec §26). Keep in sync with the spec. */
 export const GLM_DELEGATION_SKILL_NAME = "glm-delegation";
-export const GLM_DELEGATION_SKILL_MD = `---
-name: glm-delegation
-description: >
-  Delegate well-scoped implementation, testing,
-  repository exploration, boilerplate, CRUD,
-  documentation, and mechanical refactoring to
-  GLM Coding Plan workers.
----
-
-# GLM Delegation
-
-Available commands:
-
-glm-worker "<task>"
-glm-review "<task>"
-
-## Use glm-review for
-
-- repository exploration
-- dependency analysis
-- locating implementations
-- call-chain discovery
-- code review
-
-## Use glm-worker for
-
-- CRUD
-- unit tests
-- implementation
-- documentation
-- repetitive changes
-- mechanical refactoring
-
-## Keep in primary Codex agent
-
-- requirements
-- architecture
-- ambiguous rules
-- security-sensitive design
-- difficult debugging
-- integration
-- final acceptance
-
-## Delegation packet
-
-Always provide:
-
-TASK
-SCOPE
-ALLOWED FILES
-FORBIDDEN FILES
-REQUIREMENTS
-CONSTRAINTS
-ACCEPTANCE CRITERIA
-VALIDATION
-EXPECTED OUTPUT
-
-## Verification
-
-After GLM finishes:
-
-- inspect the actual diff
-- independently run relevant validation
-- compare implementation with requirements
-- reject or correct worker output when needed
+export const GLM_DELEGATION_SKILL_MD = `---
+name: glm-delegation
+description: >
+  Delegate well-scoped implementation, testing,
+  repository exploration, boilerplate, CRUD,
+  documentation, and mechanical refactoring to
+  GLM Coding Plan workers.
+---
+
+# GLM Delegation
+
+Available commands:
+
+glm-worker "<task>"
+glm-review "<task>"
+
+## Use glm-review for
+
+- repository exploration
+- dependency analysis
+- locating implementations
+- call-chain discovery
+- code review
+
+## Use glm-worker for
+
+- CRUD
+- unit tests
+- implementation
+- documentation
+- repetitive changes
+- mechanical refactoring
+
+## Keep in primary Codex agent
+
+- requirements
+- architecture
+- ambiguous rules
+- security-sensitive design
+- difficult debugging
+- integration
+- final acceptance
+
+## Delegation packet
+
+Always provide:
+
+TASK
+SCOPE
+ALLOWED FILES
+FORBIDDEN FILES
+REQUIREMENTS
+CONSTRAINTS
+ACCEPTANCE CRITERIA
+VALIDATION
+EXPECTED OUTPUT
+
+## Verification
+
+After GLM finishes:
+
+- inspect the actual diff
+- independently run relevant validation
+- compare implementation with requirements
+- reject or correct worker output when needed
 `;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "glm-coding-router",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "GLM Coding Plan workers for Claude Code and Codex",
   "type": "module",
   "license": "MIT",