glab-agent 0.2.0 → 0.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "glab-agent",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "type": "module",
   "description": "Multi-agent GitLab To-Do watcher with YAML-defined agents, skills, and GitLab registry.",
   "license": "MIT",
@@ -31,6 +31,7 @@
     "access": "public"
   },
   "scripts": {
+    "prepare": "git config core.hooksPath scripts/hooks",
     "build": "tsc -p tsconfig.build.json",
     "test": "vitest run",
     "agent": "tsx src/local-agent/cli.ts",

package/src/local-agent/cli.ts

@@ -83,8 +83,8 @@ Options:
   --project <dir>        Target project directory (default: cwd)
 
 Commands:
-  init [name]            Initialize .glab-agent/ and optionally create an agent
-                           --provider <claude|codex>  --labels <l1,l2>  --token-env <VAR>
+  init [name]            Initialize agent config (--repo for full Agents repo setup)
+                           --provider <claude|codex>  --labels <l1,l2>  --repo  -h
   list                   List all agent definitions
   start <name|--all>     Start agent(s) as background watcher process
   stop <name|--all>      Stop agent(s)
@@ -104,6 +104,9 @@ Commands:
   skills import <url>    Import skills from GitHub repo (--force to overwrite)
   wiki setup             Populate project GitLab Wiki with documentation pages
   doctor                 Check prerequisites and environment
+
+Options:
+  --version, -v          Show version
 `);
 }
 
@@ -457,6 +460,12 @@ export async function validateGitlabToken(host: string, token: string): Promise<
 }
 
 async function cmdInit(name?: string, options?: { provider?: string; labels?: string; tokenEnv?: string; repo?: boolean; botUsername?: string }): Promise<void> {
+  // Warn if not in a git repository
+  if (!existsSync(path.join(PROJECT_DIR, ".git"))) {
+    console.warn(`⚠️  No .git/ found in ${PROJECT_DIR}. Are you in the right directory?`);
+    console.warn(`   Agents repos should be git repositories. Run 'git init' first.\n`);
+  }
+
   const base = agentBaseDir(PROJECT_DIR);
   const dirs = [
     path.join(base, "agents"),
@@ -570,6 +579,7 @@ heartbeat/
     console.log(`\nNext steps:`);
     console.log(`  1. Create an agent: glab-agent init <name> --provider claude`);
     console.log(`  2. Check dependencies: glab-agent doctor`);
+    console.log(`\nTip: Use 'glab-agent init --repo' for a complete Agents management repo with README and defaults.`);
     if (remote) {
       console.log(`\nDocumentation: ${wikiUrl(remote.host, remote.projectPath, "getting-started")}`);
       console.log(`   (Run 'glab-agent wiki setup' to populate the project wiki)`);
@@ -618,9 +628,78 @@ heartbeat/
 
   // --repo: generate self-contained product landing page README (done after all init so we have remote/provider/botUsername)
   if (options?.repo) {
+    // If no agent name given with --repo, create a default one
+    let effectiveName = name;
+    if (!effectiveName) {
+      const defaultName = "my-bot";
+      const provider = (resolvedProvider === "claude" || resolvedProvider === "codex") ? resolvedProvider as "claude" | "codex" : "claude";
+      const yamlPath = path.join(base, "agents", `${defaultName}.yaml`);
+      try {
+        await readFile(yamlPath, "utf8");
+      } catch {
+        const yamlContent = generateAgentYaml(defaultName, provider, [], "GITLAB_TOKEN", { host: remote?.host });
+        await writeFile(yamlPath, yamlContent, "utf8");
+        console.log(`Created default agent: ${yamlPath}`);
+        effectiveName = defaultName;
+      }
+    }
+
+    // Create .env.example
+    const envExamplePath = path.join(base, ".env.example");
+    try {
+      await readFile(envExamplePath, "utf8");
+    } catch {
+      const host = remote?.host ?? "gitlab.com";
+      const protocol = host.startsWith("localhost") || host.startsWith("127.") ? "http" : "https";
+      const envExample = `# GitLab Personal Access Token
+# Create at: ${protocol}://${host}/-/user_settings/personal_access_tokens
+# Required scopes: api, read_user, read_repository, write_repository
+# Tip: Use a bot account's token so agent actions appear as the bot, not you.
+GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx
+`;
+      await writeFile(envExamplePath, envExample, "utf8");
+      console.log(`Created ${envExamplePath}`);
+    }
+
+    // Create default skill
+    const defaultSkillPath = path.join(base, "skills", "test-before-commit.md");
+    try {
+      await readFile(defaultSkillPath, "utf8");
+    } catch {
+      const skillContent = `---
+name: test-before-commit
+description: Always run tests before committing
+---
+
+Before committing any code change, run the project's test suite.
+If tests fail, fix the code before committing.
+Do not skip tests or use --no-verify to bypass hooks.
+`;
+      await writeFile(defaultSkillPath, skillContent, "utf8");
+      console.log(`Created default skill: ${defaultSkillPath}`);
+    }
+
+    // Create root .gitignore (for the Agents repo itself)
+    const rootGitignorePath = path.join(PROJECT_DIR, ".gitignore");
+    try {
+      await readFile(rootGitignorePath, "utf8");
+    } catch {
+      const rootGitignore = `.glab-agent/.env
+.glab-agent/state/
+.glab-agent/pid/
+.glab-agent/logs/
+.glab-agent/worktrees/
+.glab-agent/metrics/
+.glab-agent/heartbeat/
+.DS_Store
+`;
+      await writeFile(rootGitignorePath, rootGitignore, "utf8");
+      console.log(`Created .gitignore`);
+    }
+
     const readmePath = path.join(PROJECT_DIR, "README.md");
     const readmeContent = buildRepoReadme({
-      agentName: name ?? undefined,
+      agentName: effectiveName ?? undefined,
       provider: resolvedProvider,
       host: remote?.host,
       projectPath: remote?.projectPath,
@@ -634,6 +713,41 @@ heartbeat/
       await writeFile(readmePath, readmeContent, "utf8");
       console.log("Created README.md — product landing page for AI agents.");
     }
+
+    // Auto-run wiki setup if remote and token are available
+    if (remote) {
+      const token = process.env[options?.tokenEnv ?? "GITLAB_TOKEN"];
+      if (token) {
+        console.log("\nPopulating GitLab Wiki with documentation...");
+        try {
+          const client = new GitlabGlabClient({ host: remote.host, token });
+          const { stdout } = await execFileAsync("glab", ["api", `projects/${encodeURIComponent(remote.projectPath)}`], {
+            encoding: "utf8",
+            env: { ...process.env, GITLAB_HOST: remote.host, GITLAB_TOKEN: token }
+          });
+          const projectId = JSON.parse(stdout).id as number;
+          const pages = buildWikiPages(remote.host, remote.projectPath);
+          const existingPages = await client.listWikiPages(projectId);
+          const existingSlugs = new Set(existingPages.map(p => p.slug));
+          let created = 0;
+          let updated = 0;
+          for (const page of pages) {
+            try {
+              if (existingSlugs.has(page.title)) {
+                await client.updateWikiPage(projectId, page.title, page.title, page.content);
+                updated++;
+              } else {
+                await client.createWikiPage(projectId, page.title, page.content);
+                created++;
+              }
+            } catch { /* skip failed pages */ }
+          }
+          console.log(`✅ Wiki: ${created} created, ${updated} updated. ${wikiUrl(remote.host, remote.projectPath, "home")}`);
+        } catch {
+          console.log(`Skipped wiki setup (run 'glab-agent wiki setup' manually after pushing to GitLab).`);
+        }
+      }
+    }
   }
 
   // Also append to README.md for universal AI tool compatibility (non-repo mode)
@@ -741,7 +855,7 @@ async function cmdDoctor(): Promise<void> {
       label: "Agent definitions",
       ok: false,
       optional: false,
-      message: "no .yaml files found in .glab-agent/agents/"
+      message: "no agent definitions found in .glab-agent/agents/ — run 'glab-agent init <name> --provider claude' to create one"
     });
   }
 
@@ -1940,6 +2054,28 @@ export function buildClaudeMdSection(agentName?: string, host?: string, projectP
     "- Agent definitions: `.glab-agent/agents/*.yaml`",
     "- Shared skills: `.glab-agent/skills/*.md`",
     "- Tokens: `.glab-agent/.env` (gitignored)",
+    "",
+    "### Agent YAML Format",
+    "",
+    "```yaml",
+    "name: my-bot",
+    "provider: claude          # or codex",
+    "gitlab:",
+    "  token_env: GITLAB_TOKEN",
+    "prompt:",
+    "  preamble: |",
+    "    Project-specific instructions here.",
+    "triggers:",
+    "  labels: []              # empty = all issues, or [\"bug\", \"feature\"]",
+    "  exclude_labels: [\"Done\"]",
+    "skills:",
+    "  - test-before-commit",
+    "poll_interval_seconds: 60",
+    "```",
+    "",
+    "### Setup New Agents Repo",
+    "",
+    "`glab-agent init --repo` creates a complete Agents management repo with README, default agent, skills, and .env template.",
   );
   if (host && projectPath) {
     const protocol = host.startsWith("localhost") || host.startsWith("127.") ? "http" : "https";
@@ -1982,6 +2118,11 @@ export function buildAgentSkill(): string {
     "- `glab-agent history <name>` — Show recent execution history",
     "- `glab-agent report <name> --since 7d` — Performance report (add `--publish` to write to GitLab Wiki)",
     "",
+    "## Setup",
+    "- `glab-agent init <name> --provider claude` — Create a single agent",
+    "- `glab-agent init --repo` — Create a full Agents management repo (README + default agent + skills)",
+    "- `glab-agent wiki setup` — Populate GitLab Wiki with documentation",
+    "",
     "## Configuration",
     "- Agent YAML: `.glab-agent/agents/<name>.yaml`",
     "- Shared skills: `.glab-agent/skills/<name>.md`",
@@ -2078,8 +2219,39 @@ async function main(): Promise<void> {
   const command = args[0];
   const target = args[1];
 
+  // Handle --version / version / -v
+  if (command === "--version" || command === "version" || command === "-v") {
+    const pkgPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../package.json");
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+      console.log(`glab-agent v${pkg.version}`);
+    } catch {
+      console.log("glab-agent (version unknown)");
+    }
+    return;
+  }
+
   switch (command) {
     case "init": {
+      if (args.includes("--help") || args.includes("-h")) {
+        console.log(`Usage: glab-agent init [<name>] [options]
+
+Create agent configuration in the current project.
+
+Options:
+  <name>              Agent name (e.g., my-bot). Omit for base init only.
+  --provider <p>      AI provider: claude (default) or codex
+  --labels <l>        Comma-separated trigger labels
+  --token-env <var>   Token env variable name (default: GITLAB_TOKEN)
+  --repo              Generate full Agents management repo (README + default agent + skills + .env.example)
+  --help, -h          Show this help
+
+Examples:
+  glab-agent init my-bot --provider claude     # Create a Claude agent
+  glab-agent init --repo                       # Full Agents repo with README
+  glab-agent init my-bot --repo                # Agents repo + named agent`);
+        break;
+      }
       const initProvider = extractFlag(args, "--provider");
       const initLabels = extractFlag(args, "--labels");
       const initTokenEnv = extractFlag(args, "--token-env");

package/src/local-agent/watcher.ts

@@ -50,6 +50,7 @@ const ACCEPTED_TODO_ACTIONS = new Set(["mentioned", "directly_addressed"]);
 export interface LocalAgentConfig {
   gitlabHost: string;
   gitlabProjectId?: number;
+  gitlabProjectIdExplicit: boolean;  // true when YAML explicitly sets project_id
   gitlabToken: string;
   agentProvider: AgentProvider;
   agentRepoPath: string;
@@ -334,7 +335,7 @@ export async function runWatcherCycle(
 
   await updateAgentUserStatus(dependencies, "idle", undefined, config);
 
-  const todos = config.gitlabProjectId
+  const todos = config.gitlabProjectIdExplicit && config.gitlabProjectId
     ? await dependencies.gitlabClient.listPendingTodos(config.gitlabProjectId)
     : await dependencies.gitlabClient.listAllPendingTodos();
   logger.info(`Polled ${todos.length} pending todo(s).`);
@@ -823,7 +824,7 @@ async function notifyPendingTodosWhileBusy(
   let todos: GitlabTodoItem[];
 
   try {
-    todos = config.gitlabProjectId
+    todos = (config.gitlabProjectIdExplicit && config.gitlabProjectId)
       ? await dependencies.gitlabClient.listMentionedIssueTodos(config.gitlabProjectId)
       : await dependencies.gitlabClient.listAllPendingTodos();
   } catch (error) {
@@ -1039,14 +1040,16 @@ export function loadConfigFromAgentDefinition(
     throw new Error(`gitlab.host is required for agent "${def.name}" or must be inferable from git remote.`);
   }
 
+  const explicitProjectId = def.gitlab.project_id;
   const gitlabProjectId =
-    def.gitlab.project_id ??
+    explicitProjectId ??
     inferGitlabProjectId(gitlabHost, gitlabToken, agentRepoPath, execFileSyncImpl) ??
     undefined;
 
   return {
     gitlabHost,
     gitlabProjectId,
+    gitlabProjectIdExplicit: explicitProjectId != null,
     gitlabToken,
     agentProvider: def.provider,
     agentRepoPath,
@@ -1181,7 +1184,7 @@ export async function main(argv: string[] = process.argv.slice(2)): Promise<void
     process.exit(1);
   }
 
-  logger.info(`Watcher started. mode=${mode} provider=${config.agentProvider} host=${config.gitlabHost}${config.gitlabProjectId ? ` project=${config.gitlabProjectId}` : " project=auto (from todos)"}`);
+  logger.info(`Watcher started. mode=${mode} provider=${config.agentProvider} host=${config.gitlabHost}${config.gitlabProjectId ? ` project=${config.gitlabProjectId}${config.gitlabProjectIdExplicit ? "" : " (inferred, todo polling unfiltered)"}` : " project=auto (from todos)"}`);
 
   if (mode === "run-once") {
     await runWatcherCycle(config, dependencies);