gflows 0.1.17 → 1.0.0

package/src/commands/help.ts

@@ -1,5 +1,5 @@
 /**
- * Help command: print quick reference from the spec and list commands/flags.
+ * Help command: print quick reference and list commands/flags.
  * @module commands/help
  */
 
@@ -7,58 +7,67 @@ import type { ParsedArgs } from "../types.js";
 
 /**
  * Runs the help command: prints usage, commands, types, flags, and exit codes to stdout.
- * @param _args - Parsed CLI args (unused; kept for command signature consistency).
  */
 export async function run(_args: ParsedArgs): Promise<void> {
   const out = `
 gflows — Modern Git branching workflow CLI
 
 Usage: gflows <command> [type] [name] [flags]
+       gflows                 (TTY: fullscreen hub)
 
 Commands:
-  init, -I       Ensure main, create dev
-  start, -S      Create workflow branch
-  finish, -F     Merge and close branch
+  init, -I       Ensure main, create dev (TTY: wizard; optional package.json script alias)
+  start, -S      Create workflow branch (TTY: prompts if args missing)
+  finish, -F     Merge and close branch (plan + delete by default)
+  sync           Update current branch from its base
+  pr             Open PR/MR via gh or glab (correct base)
   switch, -W     Switch branch (picker or name)
   delete, -L     Delete local branch(es)
   list, -l       List branches by type
-  bump           Bump or rollback package version
-  completion     Print shell completion script
   status, -t     Show current branch flow info
+  viz            Visual branch map + flow (also shown in interactive hub)
+  doctor         Repo health checks
+  config         get/set .gflows.json
+  bump, -U       Bump or rollback package version
+  continue       Resume after merge conflict
+  undo           Undo last completed gflows operation
+  abort          Abort suspended operation
+  schema         Machine-readable command catalog (JSON)
+  mcp            Start MCP server for AI agents
+  completion     Print shell completion script
   help, -h       Show this usage
   version, -V    Show version
 
 Types: feature (-f), bugfix (-b), chore (-c), release (-r), hotfix (-x), spike (-e)
 
 Common flags:
-  -p, --push           Push after init/start/finish
-  -P, --no-push        Do not push (init/start: push is default; finish: prompts when neither -p nor -P)
+  -p, --push           Push after init/start/finish/pr
+  -P, --no-push        Do not push (init defaults to push; start does not)
   --main <name>        Main branch (init: persist to .gflows.json)
   --dev <name>         Dev branch (init: persist to .gflows.json)
   -R, --remote <name>  Remote for push (init: persist to .gflows.json)
   -o, --from <branch>  Base branch override (e.g. -o main for bugfix)
-  -B, --branch <name>  Branch name (finish: branch to finish)
-  -y, --yes            Skip confirmations
+  -B, --branch <name>  Branch name (finish/pr)
+  -y, --yes            Accept plan / skip confirmations (finish: delete default on)
   -d, --dry-run        Log actions only, no writes
   -v, --verbose        Verbose output
   -q, --quiet          Minimal output
   -C, --path <dir>     Run as if in <dir>
+  --json               Machine-readable output (status/list/doctor/config)
 
+Init:   --script-alias <name>  Add package.json script (e.g. g → "gflows")
+        --no-script-alias      Never add a script alias
 Start:  --force         Allow dirty working tree
 Finish: --no-ff         Always create merge commit; -D/--delete, -N/--no-delete;
-        -s/--sign, -T/--no-tag, -M/--tag-message, -m/--message
+        --squash, --preview, --bump; -s/--sign, -T/--no-tag, -M/--tag-message, -m/--message
+Sync:   --rebase, --force
 List:   -r, --include-remote   Include remote-tracking branches
-Switch: --move      Move current changes to the target branch
-        --restore   Save for this branch; restore target's saved state (if any)
-        --clean     Discard changes and switch clean at HEAD
-        --cancel    Abort switching
+Switch: --move | --restore | --clean | --destroy | --cancel
 
 Exit codes: 0 success, 1 usage/validation, 2 Git or system error.
 
-Hints:
-  • gflows init then gflows start feature <name> — set up and create first branch
-  • gflows finish <type> — merge current workflow branch (use -B <name> to specify branch)
-  • gflows list -r — include remote branches; gflows status — show current branch flow
+Stuck?  gflows continue | gflows abort | gflows undo | gflows doctor
+Agents: see AGENTS.md, gflows schema, gflows mcp
 `;
   console.log(out.trim());
 }

package/src/commands/init.ts

@@ -8,6 +8,7 @@ import { resolveConfig, writeConfigFile } from "../config.js";
 import { BranchNotFoundError, NotRepoError } from "../errors.js";
 import { branchList, push, resolveRepoRoot, revParse, runGit } from "../git.js";
 import { banner, hint, success } from "../out.js";
+import { ensureGflowsScriptAlias } from "../package-scripts.js";
 import type { ParsedArgs } from "../types.js";
 
 /**
@@ -20,12 +21,56 @@ import type { ParsedArgs } from "../types.js";
  */
 export async function run(args: ParsedArgs): Promise<void> {
   const repoRoot = await resolveRepoRoot(args.cwd);
+
+  // TTY setup wizard when no explicit config flags
+  let main = args.main;
+  let dev = args.dev;
+  let remote = args.remote;
+  let scriptAlias = args.noScriptAlias ? undefined : args.scriptAlias;
+  if (
+    process.stdin.isTTY &&
+    main === undefined &&
+    dev === undefined &&
+    remote === undefined &&
+    !args.yes
+  ) {
+    const { confirmPrompt, inputPrompt, selectPrompt } = await import("../prompts.js");
+    const defaults = resolveConfig(repoRoot, {}, { verbose: args.verbose });
+    main = await inputPrompt({ message: "Main branch name", defaultValue: defaults.main });
+    dev = await inputPrompt({ message: "Dev branch name", defaultValue: defaults.dev });
+    remote = await inputPrompt({ message: "Remote name", defaultValue: defaults.remote });
+    const persist = await confirmPrompt({ message: "Write .gflows.json?", initialValue: true });
+    if (persist && !args.dryRun) {
+      writeConfigFile(repoRoot, { main, dev, remote });
+    }
+    if (!args.noScriptAlias && scriptAlias === undefined) {
+      const aliasChoice = await selectPrompt({
+        message: "Add a short script in package.json? (shell alias is still nicer — see docs)",
+        options: [
+          {
+            value: "g",
+            label: '"g": "gflows"',
+            hint: "bun run g -- start feature x",
+          },
+          {
+            value: "gflows",
+            label: '"gflows": "gflows"',
+            hint: "bun run gflows -- …",
+          },
+          { value: "skip", label: "Skip", hint: "use a shell alias instead" },
+        ],
+        initialValue: "g",
+      });
+      scriptAlias = aliasChoice === "skip" ? undefined : aliasChoice;
+    }
+  }
+
   const config = resolveConfig(
     repoRoot,
     {
-      main: args.main,
-      dev: args.dev,
-      remote: args.remote,
+      main,
+      dev,
+      remote,
     },
     { verbose: args.verbose },
   );
@@ -72,32 +117,68 @@ export async function run(args: ParsedArgs): Promise<void> {
 
   const doPush = !args.noPush;
   if (doPush) {
-    const pushCode = await push(repoRoot, config.remote, [config.dev], false, opts);
-    if (pushCode !== 0) {
-      throw new Error(
-        `Push failed. Local branch '${config.dev}' was created. Retry with \`git push ${config.remote} ${config.dev}\` or \`gflows init\`.`,
-      );
-    }
-    if (!args.quiet && !args.dryRun) {
-      success(`gflows: pushed '${config.dev}' to '${config.remote}'.`);
+    const remotes = await runGit(["remote"], { cwd: repoRoot, ...opts });
+    const hasRemote = remotes.stdout
+      .split("\n")
+      .map((s) => s.trim())
+      .includes(config.remote);
+    if (!hasRemote) {
+      if (!args.quiet) {
+        hint(
+          `Remote '${config.remote}' not found — skipped push. Add a remote or re-run with --no-push.`,
+        );
+      }
+    } else {
+      const pushCode = await push(repoRoot, config.remote, [config.dev], false, opts);
+      if (pushCode !== 0) {
+        throw new Error(
+          `Push failed. Local branch '${config.dev}' was created. Retry with \`git push ${config.remote} ${config.dev}\` or \`gflows init --no-push\`.`,
+        );
+      }
+      if (!args.quiet && !args.dryRun) {
+        success(`gflows: pushed '${config.dev}' to '${config.remote}'.`);
+      }
     }
   }
 
-  const hasConfigFlags =
-    args.main !== undefined || args.dev !== undefined || args.remote !== undefined;
+  const hasConfigFlags = main !== undefined || dev !== undefined || remote !== undefined;
   if (!args.dryRun && hasConfigFlags) {
     writeConfigFile(repoRoot, {
-      ...(args.main !== undefined && { main: args.main }),
-      ...(args.dev !== undefined && { dev: args.dev }),
-      ...(args.remote !== undefined && { remote: args.remote }),
+      ...(main !== undefined && { main }),
+      ...(dev !== undefined && { dev }),
+      ...(remote !== undefined && { remote }),
     });
     if (!args.quiet) {
       success("gflows: updated .gflows.json with provided options.");
     }
   }
 
+  if (scriptAlias && !args.noScriptAlias) {
+    const result = ensureGflowsScriptAlias(repoRoot, scriptAlias, { dryRun: args.dryRun });
+    if (!args.quiet) {
+      if (result.status === "added") {
+        success(
+          args.dryRun
+            ? `gflows: would add scripts["${result.name}"] = "gflows" to package.json.`
+            : `gflows: added scripts["${result.name}"] = "gflows" to package.json.`,
+        );
+        hint(`Run with: bun run ${result.name} -- start feature <name>`);
+        hint("Even shorter daily use: alias g=gflows  (or alias g='bunx gflows')");
+      } else if (result.status === "unchanged") {
+        hint(`package.json already has scripts["${result.name}"] → gflows.`);
+      } else if (result.status === "conflict") {
+        hint(`Skipped script alias: scripts["${result.name}"] is already "${result.existing}".`);
+      } else if (result.status === "no-package") {
+        hint("No package.json here — skipped script alias. Use: alias g=gflows");
+      } else if (result.status === "invalid") {
+        hint(`Invalid script alias name '${result.name}'. Use letters/numbers/_-: (e.g. g).`);
+      }
+    }
+  } else if (!args.quiet) {
+    hint("Tip: alias g=gflows in your shell, or re-run init with --script-alias g");
+  }
+
   if (!args.quiet) {
-    // Hint: suggest next step — create first workflow branch
-    hint("Run gflows start feature <name> to create a workflow branch.");
+    hint("Next: gflows start feature <name>");
   }
 }

package/src/commands/list.ts

@@ -71,12 +71,17 @@ export async function run(args: ParsedArgs): Promise<void> {
   const mainAndDev = [config.main, config.dev].filter((b) => allBranches.includes(b));
   const sorted = [...mainAndDev, ...[...workflowBranches].sort()];
 
+  if (args.json) {
+    console.log(JSON.stringify({ branches: sorted }, null, 2));
+    return;
+  }
+
   for (const b of sorted) {
     console.log(b);
   }
 
   if (!quiet && sorted.length > 0) {
-    // Hint: suggest switching to a listed branch
+    // Hint on stderr — stdout stays script-friendly
     hint("Use gflows switch <branch> to switch to a branch.");
   }
 }

package/src/commands/mcp.ts

@@ -0,0 +1,238 @@
+/**
+ * Thin stdio MCP server exposing gflows tools for coding agents.
+ * @module commands/mcp
+ */
+
+import { EXIT_OK } from "../constants.js";
+import type { ParsedArgs } from "../types.js";
+
+interface JsonRpcRequest {
+  jsonrpc?: string;
+  id?: string | number | null;
+  method?: string;
+  params?: Record<string, unknown>;
+}
+
+const TOOLS = [
+  {
+    name: "gflows_status",
+    description: "Show current branch flow info (non-interactive).",
+    inputSchema: {
+      type: "object",
+      properties: { path: { type: "string", description: "Repo path" }, json: { type: "boolean" } },
+    },
+  },
+  {
+    name: "gflows_doctor",
+    description: "Run repo health checks.",
+    inputSchema: {
+      type: "object",
+      properties: { path: { type: "string" } },
+    },
+  },
+  {
+    name: "gflows_list",
+    description: "List workflow branches.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string" },
+        type: { type: "string" },
+        includeRemote: { type: "boolean" },
+      },
+    },
+  },
+  {
+    name: "gflows_start",
+    description: "Create a workflow branch. Requires type and name.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string" },
+        type: { type: "string" },
+        name: { type: "string" },
+        from: { type: "string" },
+        push: { type: "boolean" },
+      },
+      required: ["type", "name"],
+    },
+  },
+  {
+    name: "gflows_sync",
+    description: "Sync current workflow branch from its base.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string" },
+        rebase: { type: "boolean" },
+        force: { type: "boolean" },
+      },
+    },
+  },
+  {
+    name: "gflows_finish",
+    description: "Finish a workflow branch (non-interactive; pass -y and push flag).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string" },
+        branch: { type: "string" },
+        type: { type: "string" },
+        push: { type: "boolean" },
+        noDelete: { type: "boolean" },
+        preview: { type: "boolean" },
+      },
+    },
+  },
+  {
+    name: "gflows_schema",
+    description: "Return the gflows command schema JSON.",
+    inputSchema: { type: "object", properties: {} },
+  },
+] as const;
+
+function respond(id: string | number | null | undefined, result: unknown): void {
+  const msg = { jsonrpc: "2.0", id: id ?? null, result };
+  console.log(JSON.stringify(msg));
+}
+
+function respondError(id: string | number | null | undefined, message: string): void {
+  console.log(
+    JSON.stringify({
+      jsonrpc: "2.0",
+      id: id ?? null,
+      error: { code: -32000, message },
+    }),
+  );
+}
+
+async function runTool(
+  name: string,
+  args: Record<string, unknown>,
+): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+  const cliPath = new URL("../cli.ts", import.meta.url).pathname;
+  const path = typeof args.path === "string" ? args.path : process.cwd();
+  const argv: string[] = ["-C", path, "-y"];
+
+  switch (name) {
+    case "gflows_status":
+      argv.push("status");
+      if (args.json !== false) argv.push("--json");
+      break;
+    case "gflows_doctor":
+      argv.push("doctor", "--json");
+      break;
+    case "gflows_list":
+      argv.push("list", "-q");
+      if (typeof args.type === "string") argv.push(args.type);
+      if (args.includeRemote) argv.push("-r");
+      break;
+    case "gflows_start":
+      argv.push("start", String(args.type), String(args.name));
+      if (typeof args.from === "string") argv.push("-o", args.from);
+      if (args.push) argv.push("-p");
+      else argv.push("-P");
+      break;
+    case "gflows_sync":
+      argv.push("sync");
+      if (args.rebase) argv.push("--rebase");
+      if (args.force) argv.push("--force");
+      break;
+    case "gflows_finish":
+      argv.push("finish");
+      if (typeof args.type === "string") argv.push(args.type);
+      if (typeof args.branch === "string") argv.push("-B", args.branch);
+      if (args.preview) argv.push("--preview");
+      if (args.noDelete) argv.push("-N");
+      if (args.push) argv.push("-p");
+      else argv.push("-P");
+      break;
+    case "gflows_schema":
+      argv.push("schema");
+      break;
+    default:
+      return { stdout: "", stderr: `Unknown tool ${name}`, exitCode: 1 };
+  }
+
+  const proc = Bun.spawn(["bun", cliPath, ...argv], {
+    cwd: path,
+    stdout: "pipe",
+    stderr: "pipe",
+    env: { ...process.env },
+  });
+  const [stdout, stderr] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+  ]);
+  const exitCode = await proc.exited;
+  return { stdout, stderr, exitCode };
+}
+
+/**
+ * Starts a minimal JSON-RPC MCP-like stdio loop.
+ */
+export async function run(_args: ParsedArgs): Promise<void> {
+  console.error(
+    "gflows mcp: listening on stdio (JSON-RPC). Tools: status, doctor, list, start, sync, finish, schema.",
+  );
+
+  const decoder = new TextDecoder();
+  let buffer = "";
+
+  for await (const chunk of Bun.stdin.stream()) {
+    buffer += decoder.decode(chunk);
+    const lines = buffer.split("\n");
+    buffer = lines.pop() ?? "";
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      let req: JsonRpcRequest;
+      try {
+        req = JSON.parse(trimmed) as JsonRpcRequest;
+      } catch {
+        continue;
+      }
+
+      if (req.method === "initialize") {
+        respond(req.id, {
+          protocolVersion: "2024-11-05",
+          capabilities: { tools: {} },
+          serverInfo: { name: "gflows", version: "1.0.0" },
+        });
+        continue;
+      }
+      if (req.method === "notifications/initialized") {
+        continue;
+      }
+      if (req.method === "tools/list") {
+        respond(req.id, { tools: TOOLS });
+        continue;
+      }
+      if (req.method === "tools/call") {
+        const params = req.params ?? {};
+        const name = String(params.name ?? "");
+        const toolArgs = (params.arguments ?? {}) as Record<string, unknown>;
+        try {
+          const result = await runTool(name, toolArgs);
+          respond(req.id, {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify(result),
+              },
+            ],
+            isError: result.exitCode !== 0,
+          });
+        } catch (err) {
+          respondError(req.id, err instanceof Error ? err.message : String(err));
+        }
+        continue;
+      }
+      if (req.method === "ping") {
+        respond(req.id, {});
+      }
+    }
+  }
+
+  process.exit(EXIT_OK);
+}

package/src/commands/pr.ts

@@ -0,0 +1,120 @@
+/**
+ * Open a pull/merge request against the correct merge target via gh or glab.
+ * @module commands/pr
+ */
+
+import { resolveConfig } from "../config.js";
+import { EXIT_GIT, EXIT_USER } from "../constants.js";
+import {
+  classifyBranch,
+  formatMergeTarget,
+  parseBranchTypeAndVersion,
+  primaryTargetBranch,
+  resolveMergeTarget,
+} from "../flow.js";
+import { assertNotDetached, getCurrentBranch, push, resolveRepoRoot, runGit } from "../git.js";
+import { hint, success } from "../out.js";
+import type { ParsedArgs } from "../types.js";
+
+async function which(cmd: string): Promise<boolean> {
+  const r = Bun.spawn(["which", cmd], { stdout: "pipe", stderr: "pipe" });
+  await r.exited;
+  return r.exitCode === 0;
+}
+
+/**
+ * Creates a PR/MR for the current (or named) workflow branch.
+ */
+export async function run(args: ParsedArgs): Promise<void> {
+  const repoRoot = await resolveRepoRoot(args.cwd);
+  const config = resolveConfig(
+    repoRoot,
+    { main: args.main, dev: args.dev, remote: args.remote },
+    { verbose: args.verbose },
+  );
+  const opts = { dryRun: args.dryRun, verbose: args.verbose };
+
+  await assertNotDetached(repoRoot);
+  const branch =
+    (typeof args.branch === "string" && args.branch.trim()) ||
+    args.name ||
+    (await getCurrentBranch(repoRoot, opts));
+  if (!branch) {
+    console.error("gflows pr: no branch. Checkout a workflow branch or pass -B <name>.");
+    process.exit(EXIT_USER);
+  }
+
+  const classification = classifyBranch(branch, config);
+  if (classification === "main" || classification === "dev" || classification === null) {
+    console.error(`gflows pr: '${branch}' is not a workflow branch.`);
+    process.exit(EXIT_USER);
+  }
+
+  const parsed = parseBranchTypeAndVersion(branch, config.prefixes);
+  const type = parsed?.type ?? classification;
+  const mergeTarget = await resolveMergeTarget(repoRoot, branch, type, config, opts);
+  const base = primaryTargetBranch(mergeTarget, config);
+
+  const hasGh = await which("gh");
+  const hasGlab = await which("glab");
+  if (!hasGh && !hasGlab) {
+    console.error("gflows pr: neither `gh` nor `glab` found on PATH.");
+    hint("Install GitHub CLI (gh) or GitLab CLI (glab), then retry.");
+    process.exit(EXIT_GIT);
+  }
+
+  console.error("gflows pr plan:");
+  console.error(`  head: ${branch}`);
+  console.error(`  base: ${base}`);
+  console.error(`  via:  ${hasGh ? "gh" : "glab"}`);
+
+  if (args.dryRun || args.preview) {
+    success("gflows: preview only (no PR created).");
+    return;
+  }
+
+  // Ensure upstream
+  const remote = args.remote ?? config.remote;
+  const pushCode = await push(repoRoot, remote, [branch], false, opts);
+  if (pushCode !== 0) {
+    // try set upstream
+    const r = await runGit(["push", "-u", remote, branch], { cwd: repoRoot, ...opts });
+    if (r.exitCode !== 0) {
+      console.error("gflows pr: failed to push branch to remote.");
+      process.exit(EXIT_GIT);
+    }
+  }
+
+  const title = branch;
+  if (hasGh) {
+    const proc = Bun.spawn(
+      ["gh", "pr", "create", "--base", base, "--head", branch, "--title", title, "--body", ""],
+      { cwd: repoRoot, stdout: "inherit", stderr: "inherit" },
+    );
+    const code = await proc.exited;
+    if (code !== 0) process.exit(EXIT_GIT);
+  } else {
+    const proc = Bun.spawn(
+      [
+        "glab",
+        "mr",
+        "create",
+        "--target-branch",
+        base,
+        "--source-branch",
+        branch,
+        "--title",
+        title,
+        "--yes",
+      ],
+      { cwd: repoRoot, stdout: "inherit", stderr: "inherit" },
+    );
+    const code = await proc.exited;
+    if (code !== 0) process.exit(EXIT_GIT);
+  }
+
+  if (!args.quiet) {
+    success(`gflows: opened PR/MR for '${branch}' → ${base}.`);
+    hint(`Merge target(s) for this type: ${formatMergeTarget(mergeTarget, config)}.`);
+  }
+}