glab-agent 0.2.0 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "glab-agent",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "type": "module",
   "description": "Multi-agent GitLab To-Do watcher with YAML-defined agents, skills, and GitLab registry.",
   "license": "MIT",

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,
@@ -741,7 +820,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 +2019,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 +2083,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 +2184,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");