feature-flow-cli 0.1.0__py3-none-any.whl

feature_flow/gate.py

@@ -0,0 +1,100 @@
+"""The gate: a port of the bash gate in scripts/.
+
+usage: python3 scripts/gate.py <feature>
+runs the Build, Test and Lint commands from plans/<feature>/commands.md in that order and
+stops at the first one that fails. empty values and placeholders in angle brackets are skipped.
+the commands run from the current directory and must exit non zero on failure.
+exit 0 everything passed or nothing to run, 1 a command failed, 2 usage error.
+
+The file is read and the output written as bytes, so the text matches the bash version byte for
+byte (awk keeps a trailing carriage return, and tail prints a command's output unchanged).
+"""
+
+import os
+import re
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+KEYS = ("Build", "Test", "Lint")
+TAIL = 40
+
+
+def shell(cmd):
+    """How to run a command from commands.md: bash -c on Linux and macOS, the system shell (cmd.exe)
+    on Windows, where `bash` on PATH may be the Windows Subsystem for Linux stub and git-bash is not
+    a requirement. Returns (args, use_shell) for subprocess."""
+    if sys.platform == "win32":
+        return cmd, True
+    return ["bash", "-c", cmd], False
+
+
+def command(path, key):
+    """The first `<key>:` line of commands.md, as the awk line in the bash gate reads it, or b""."""
+    key = key.encode()
+    try:
+        data = Path(path).read_bytes()
+    except OSError:  # awk prints its own error to stderr and the value is empty
+        return b""
+    for line in data.split(b"\n"):  # a Windows checkout may end lines with \r; it is dropped below
+        if line.startswith(key + b":"):
+            value = re.sub(b"^" + re.escape(key) + b":[ \t]*", b"", line, count=1)
+            return value.rstrip(b"\r").replace(b"`", b"")
+    return b""
+
+
+def tail(data, n=TAIL):
+    """The last n lines of data, as tail -n prints them (a last line without a newline counts)."""
+    if not data:
+        return b""
+    if data.endswith(b"\n"):
+        return b"\n".join(data[:-1].split(b"\n")[-n:]) + b"\n"
+    return b"\n".join(data.split(b"\n")[-n:])
+
+
+def run(feature, out, err):
+    """Run the gate for feature. out and err take bytes. Returns the exit code."""
+    if not feature:
+        # the bash gate's usage line, word for word (parity); ticket 07 switches it to gate.py
+        err(b"usage: python3 scripts/gate.py <feature>\n")
+        return 2
+    name = os.fsencode(feature)
+    path = Path(os.environ.get("FLOW_DIR") or "plans") / feature / "commands.md"
+    if not path.is_file():
+        out(b"gate: no commands.md for " + name + b", nothing to run\n")
+        return 0
+    ran = 0
+    for key in KEYS:
+        cmd = command(path, key)
+        if cmd == b"" or cmd.startswith(b"<"):
+            continue
+        ran += 1
+        out(b"gate: " + key.encode() + b": " + cmd + b"\n")
+        with tempfile.TemporaryFile() as log:
+            args, use_shell = shell(os.fsdecode(cmd))
+            code = subprocess.call(args, shell=use_shell, stdout=log, stderr=subprocess.STDOUT)
+            if code != 0:
+                log.seek(0)
+                out(b"gate: " + key.encode() + b" failed. the last lines of its output:\n")
+                out(tail(log.read()))
+                return 1
+    if ran > 0:
+        out(b"gate: %d command(s) passed\n" % ran)
+    else:
+        out(b"gate: no commands defined, nothing to run\n")
+    return 0
+
+
+def _writer(stream):
+    def write(data):
+        stream.buffer.write(data)
+        stream.buffer.flush()
+    return write
+
+
+def main(argv=None):
+    argv = sys.argv[1:] if argv is None else argv
+    sys.stdout.flush()
+    sys.stderr.flush()
+    return run(argv[0] if argv else "", _writer(sys.stdout), _writer(sys.stderr))

feature_flow/git.py

@@ -0,0 +1,47 @@
+"""The few git calls the conductor needs, each one an argument list, never a shell string."""
+
+import subprocess
+from pathlib import Path
+
+
+def _git(*args, check=True):
+    result = subprocess.run(["git"] + list(args), stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+                            universal_newlines=True)
+    if check and result.returncode != 0:
+        raise RuntimeError("git %s failed: %s" % (" ".join(args), result.stderr.strip()))
+    return result
+
+
+def git_dir():
+    result = _git("rev-parse", "--absolute-git-dir", check=False)
+    if result.returncode != 0:
+        return None
+    return Path(result.stdout.strip())
+
+
+def toplevel():
+    result = _git("rev-parse", "--show-toplevel", check=False)
+    if result.returncode != 0 or not result.stdout.strip():
+        return None
+    return Path(result.stdout.strip())
+
+
+def head():
+    return _git("rev-parse", "HEAD").stdout.strip()
+
+
+def is_clean():
+    """No change at all, untracked files included, as `git status --porcelain` sees it."""
+    return _git("status", "--porcelain").stdout.strip() == ""
+
+
+def tracked_clean():
+    """No change to a tracked file, in the worktree or the index."""
+    return (_git("diff", "--quiet", check=False).returncode == 0
+            and _git("diff", "--cached", "--quiet", check=False).returncode == 0)
+
+
+def commit_file(path, message):
+    if _git("add", "--", str(path), check=False).returncode != 0:
+        return False
+    return _git("commit", "-q", "-m", message, check=False).returncode == 0

feature_flow/install.py

@@ -0,0 +1,365 @@
+"""The installer, ported from install.sh with the same report and exit codes.
+
+usage: python3 install.py [target-repo] [--agent claude|codex|all] [--user] [--force] [--dry-run]
+copies the feature-flow skill, its roles, scripts and guides into a repo so the flow works there.
+a file that already exists and differs is kept and reported, unless --force is given.
+nothing is ever deleted. CLAUDE_HOME overrides ~/.claude and AGENTS_HOME overrides ~/.agents for --user.
+
+Files are compared and written as bytes, and the two text transforms (the Codex skill header and
+a role file without its frontmatter) follow the awk programs of the bash version line for line,
+so the installed tree is the same byte for byte. Files are listed in byte order, as `sort` does
+with LC_ALL=C.
+"""
+
+import os
+import re
+import shutil
+import subprocess
+import sys
+
+# the help text
+USAGE = """\
+usage: python3 install.py [target-repo] [--agent claude|codex|all] [--user] [--force] [--dry-run]
+copies the feature-flow skill, its roles, scripts and guides into a repo so the flow works there.
+  --agent claude (default)
+    skills  go to <target>/.claude/skills/   (or ~/.claude/skills/ with --user)
+    agents  go to <target>/.claude/agents/   (or ~/.claude/agents/ with --user)
+  --agent codex: the Codex skill from adapters/codex/, the other skills with a Codex header
+    skills  go to <target>/.agents/skills/   (or ~/.agents/skills/ with --user)
+    roles   go to <target>/.agents/flow-roles/ (always: the skill reads them from the repo)
+  --agent all does both.
+  scripts go to <target>/scripts/ and guides, roles and the Python package to <target>/.feature-flow/
+    (always: the skill and scripts/flow.py read them from the repo)
+a file that already exists and differs is kept and reported, unless --force is given.
+nothing is ever deleted. CLAUDE_HOME overrides ~/.claude and AGENTS_HOME overrides ~/.agents for --user.
+"""
+
+# inside an installed package the skills, roles, guides and scripts sit in this folder of feature_flow
+BUNDLE = "_bundle"
+
+# the skills this installs
+SKILLS = ("feature-flow", "architect-review", "automation-design")
+
+# an old skill that runs the ticket script (the bash one or the Python one) or ends a review with a verdict
+LEFTOVER = re.compile(rb"scripts/flow-status\.(?:sh|py)|REVIEW: PASS")
+
+
+class Usage(Exception):
+    """A usage error: the message, and whether the help text follows it."""
+
+    def __init__(self, message, help_too=False):
+        Exception.__init__(self, message)
+        self.help_too = help_too
+
+
+def _lines(data):
+    """The records awk reads: split on newlines, a last line without one still counts."""
+    if not data:
+        return []
+    lines = data.split(b"\n")
+    if data.endswith(b"\n"):
+        lines.pop()
+    return lines
+
+
+def codex_header(data):
+    """A Codex skill header holds only the name and a quoted description; the body is left as it is."""
+    out = []
+    fm = False
+    for nr, line in enumerate(_lines(data), 1):
+        if nr == 1 and line == b"---":
+            fm = True
+            out.append(line)
+        elif fm and line == b"---":
+            fm = False
+            out.append(line)
+        elif fm and line.startswith(b"name:"):
+            out.append(line)
+        elif fm and line.startswith(b"description:"):
+            d = re.sub(rb"[ \t]+$", b"", re.sub(rb"^[ \t]+", b"", line[12:], count=1), count=1)
+            e = d.replace(b"\\", b"\\\\").replace(b'"', b'\\"')
+            out.append(b'description: "' + e + b'"')
+        elif fm:
+            continue
+        else:
+            out.append(line)
+    return b"".join(line + b"\n" for line in out)
+
+
+def role_body(data):
+    """A role file without its frontmatter (and the blank lines after it), to go in front of a prompt."""
+    out = []
+    fm = skip = False
+    for nr, line in enumerate(_lines(data), 1):
+        if nr == 1 and line == b"---":
+            fm = True
+        elif fm and line == b"---":
+            fm = False
+            skip = True
+        elif fm:
+            continue
+        elif skip and line == b"":
+            continue
+        else:
+            skip = False
+            out.append(line)
+    return b"".join(line + b"\n" for line in out)
+
+
+def _files(src, skip_python=True):
+    """`find src -type f ! -name .DS_Store [! -name '*.pyc' ! -path '*/__pycache__/*'] | sort`."""
+    found = []
+    for top, _dirs, names in os.walk(src):
+        rel = os.path.relpath(top, src).replace(os.sep, "/")
+        prefix = src + "/" if rel == "." else src + "/" + rel + "/"
+        for name in names:
+            path = prefix + name
+            if os.path.islink(path) or not os.path.isfile(path) or name == ".DS_Store":
+                continue
+            if skip_python and (name.endswith(".pyc") or "/__pycache__/" in path):
+                continue
+            found.append(path)
+    return sorted(found, key=os.fsencode)
+
+
+def source_root():
+    """Where the skills, roles, guides and scripts are: the copy inside an installed package, else the checkout."""
+    package = os.path.dirname(os.path.abspath(__file__))
+    bundle = os.path.join(package, BUNDLE)
+    return bundle if os.path.isdir(bundle) else os.path.dirname(package)
+
+
+def _read(path):
+    try:
+        with open(path, "rb") as f:
+            return f.read()
+    except OSError:
+        return None
+
+
+def _logical_cwd():
+    """The directory bash's pwd prints: $PWD when it names the current directory, else the real one."""
+    pwd = os.environ.get("PWD", "")
+    try:
+        if os.path.isabs(pwd) and os.path.samefile(pwd, "."):
+            return os.path.normpath(pwd)
+    except OSError:
+        pass
+    return os.getcwd()
+
+
+class Installer:
+    def __init__(self, here, target, agent, user_level, force, dry, out):
+        self.here = here
+        self.target = target
+        self.agent = agent
+        self.force = force
+        self.dry = dry
+        self.out = out
+        if user_level:
+            home = os.environ.get("HOME", "")
+            self.claude_dir = os.environ.get("CLAUDE_HOME") or home + "/.claude"
+            self.agents_dir = os.environ.get("AGENTS_HOME") or home + "/.agents"
+        else:
+            self.claude_dir = target + "/.claude"
+            self.agents_dir = target + "/.agents"
+        # the Python package: the checkout's, else (inside an installed package) this one
+        package = here + "/feature_flow"
+        if not os.path.isfile(package + "/__init__.py"):
+            package = os.path.dirname(os.path.abspath(__file__))
+        self.package = package
+        self.added = self.updated = self.same = self.kept = 0
+
+    def place(self, file, dest, data=None):
+        """One file: add it, replace it (--force), leave it alone (same) or keep the user's version.
+        data is a transformed copy of file, written with mode 644."""
+        new = _read(file) if data is None else data
+        if not os.path.exists(dest):
+            self.out("  add     " + dest)
+            self.added += 1
+            if not self.dry:
+                os.makedirs(os.path.dirname(dest), exist_ok=True)
+                self._copy(file, dest, data)
+        elif new is not None and _read(dest) == new:
+            self.same += 1
+        elif self.force:
+            self.out("  update  " + dest)
+            self.updated += 1
+            if not self.dry:
+                self._copy(file, dest, data)
+        else:
+            self.out("  kept    " + dest + " (differs from this version, use --force to replace it)")
+            self.kept += 1
+
+    @staticmethod
+    def _copy(file, dest, data):
+        """cp -p: contents, mode and times."""
+        if data is None:
+            shutil.copy2(file, dest)
+            return
+        with open(dest, "wb") as f:
+            f.write(data)
+        os.chmod(dest, 0o644)
+
+    def copy_tree(self, src, dest, skip=None):
+        """Every file under src, except those under src/skip."""
+        if not os.path.isdir(src):
+            return
+        for file in _files(src):
+            rel = file[len(src) + 1:]
+            if skip and rel.startswith(skip + "/"):
+                continue
+            self.place(file, dest + "/" + rel)
+
+    def install_codex(self):
+        here = self.here
+        self.copy_tree(here + "/adapters/codex/feature-flow", self.agents_dir + "/skills/feature-flow")
+        for name in SKILLS:
+            if name == "feature-flow":
+                continue
+            skill = here + "/skills/" + name
+            for file in _files(skill, skip_python=False) if os.path.isdir(skill) else []:
+                if file == skill + "/SKILL.md":
+                    data = _read(file)
+                    self.place(file, self.agents_dir + "/skills/" + name + "/SKILL.md",
+                               codex_header(data if data is not None else b""))
+                else:
+                    self.place(file, self.agents_dir + "/skills/" + name + "/" + file[len(skill) + 1:])
+        agents = here + "/agents"
+        names = sorted(os.listdir(agents), key=os.fsencode) if os.path.isdir(agents) else []
+        for name in names:
+            file = agents + "/" + name
+            if name.startswith(".") or not name.endswith(".md") or not os.path.isfile(file):
+                continue
+            data = _read(file)
+            self.place(file, self.target + "/.agents/flow-roles/" + name,
+                       role_body(data if data is not None else b""))
+
+    def report_leftovers(self, dirs):
+        """A skill folder this installer does not own but that drives the flow (it runs the ticket
+        scripts or ends a review with a verdict) is left from an earlier version: named once, never deleted."""
+        found = ""
+        for d in dirs:
+            names = sorted(os.listdir(d), key=os.fsencode) if os.path.isdir(d) else []
+            for name in names:
+                path = d + "/" + name + "/SKILL.md"
+                if name.startswith(".") or not os.path.isfile(path) or name in SKILLS:
+                    continue
+                data = _read(path)
+                if data is not None and LEFTOVER.search(data):
+                    found += " " + name
+        if found:
+            self.out("note: left from an earlier feature-flow, no longer installed:" + found
+                     + ". delete them, /feature-flow replaces them")
+
+    def run(self):
+        here, agent = self.here, self.agent
+        if self.dry:
+            self.out("dry run: nothing will be written")
+        self.out("installing into " + self.target + ("" if agent == "claude" else " (%s)" % agent))
+        left = []
+        if agent in ("claude", "all"):
+            for name in SKILLS:
+                self.copy_tree(here + "/skills/" + name, self.claude_dir + "/skills/" + name)
+            self.copy_tree(here + "/agents", self.claude_dir + "/agents")
+            left.append(self.claude_dir + "/skills")
+        if agent in ("codex", "all"):
+            self.install_codex()
+            left.append(self.agents_dir + "/skills")
+        self.copy_tree(here + "/scripts", self.target + "/scripts")
+        self.copy_tree(here + "/guides", self.target + "/.feature-flow/guides")
+        self.copy_tree(here + "/agents", self.target + "/.feature-flow/agents")
+        self.copy_tree(self.package, self.target + "/.feature-flow/feature_flow", skip=BUNDLE)
+
+        self.out("")
+        verb = "would add" if self.dry else "added"
+        self.out("%s %d, updated %d, already current %d, kept %d"
+                 % (verb, self.added, self.updated, self.same, self.kept))
+        self.report_leftovers(left)
+
+        if not self.dry:
+            try:
+                git = subprocess.run(["git", "-C", self.target, "rev-parse", "--git-dir"],
+                                     stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL).returncode
+            except OSError:
+                git = 127
+            if git != 0:
+                self.out("note: %s is not a git repository, and the flow needs one" % self.target)
+            if not shutil.which("python3"):
+                self.out("note: install python3 (3.9 or later): scripts/flow.py needs it")
+            if agent in ("claude", "all"):
+                self.out("next: /feature-flow <feature-name> in Claude Code")
+            if agent in ("codex", "all"):
+                self.out("next: $feature-flow <feature-name> in Codex")
+        return 0
+
+
+def parse(argv):
+    """The options, read in order like the bash case statement. Returns a dict, or None for --help."""
+    opts = {"target": "", "agent": "claude", "user": False, "force": False, "dry": False}
+    i = 0
+    while i < len(argv):
+        a = argv[i]
+        if a == "--agent":
+            if i + 1 >= len(argv):
+                raise Usage("--agent needs a value: claude, codex or all", help_too=True)
+            i += 1
+            opts["agent"] = argv[i]
+        elif a.startswith("--agent="):
+            opts["agent"] = a[len("--agent="):]
+        elif a == "--user":
+            opts["user"] = True
+        elif a == "--force":
+            opts["force"] = True
+        elif a == "--dry-run":
+            opts["dry"] = True
+        elif a in ("-h", "--help"):
+            return None
+        elif a.startswith("-"):
+            raise Usage("unknown option: " + a, help_too=True)
+        else:
+            opts["target"] = a
+        i += 1
+    if opts["agent"] not in ("claude", "codex", "all"):
+        raise Usage("unknown agent: %s (use claude, codex or all)" % opts["agent"])
+    return opts
+
+
+def run(argv, here, out, err):
+    """Run the installer. out and err take one line of text each. Returns the exit code."""
+    try:
+        opts = parse(argv)
+    except Usage as e:
+        err(str(e))
+        if e.help_too:
+            err(USAGE[:-1])
+        return 2
+    if opts is None:
+        out(USAGE[:-1])
+        return 0
+    target = opts["target"] or "."
+    if not os.path.isdir(target):
+        err("no such directory: " + target)
+        return 2
+    target = os.path.normpath(os.path.join(_logical_cwd(), target))
+    installer = Installer(os.path.abspath(str(here)), target, opts["agent"], opts["user"],
+                          opts["force"], opts["dry"], out)
+    return installer.run()
+
+
+def main(here, argv=None):
+    """The command line: writes each line as bytes, flushed, so stdout and stderr keep their order."""
+    argv = sys.argv[1:] if argv is None else argv
+
+    def writer(stream):
+        def write(line):
+            stream.buffer.write(os.fsencode(line) + b"\n")
+            stream.buffer.flush()
+        return write
+
+    sys.stdout.flush()
+    try:
+        return run(argv, here, writer(sys.stdout), writer(sys.stderr))
+    except OSError as e:  # cp or mkdir failed: the bash installer stopped there too (set -e)
+        writer(sys.stderr)("install.py: %s" % e)
+        return 1

feature_flow/prompts.py

@@ -0,0 +1,52 @@
+"""The prompts a session hands to its builder and reviewer, built from the role files and the guides.
+
+The text is runtime neutral: any agent that can read a prompt can follow it.
+"""
+
+from pathlib import Path
+
+ROLES = {"build": "ticket-builder.md", "review": "ticket-reviewer.md"}
+GUIDES = {"build": "build.md", "review": "review.md"}
+
+
+def find_file(scripts, folder, name):
+    """folder/name beside the scripts folder (a checkout), else in .feature-flow/ (an install).
+
+    A candidate counts only when it holds the file, so an unrelated guides/ or agents/ folder
+    in the user's repo does not hide the installed one.
+    """
+    for root in (Path(scripts).parent, Path(".feature-flow")):
+        path = root / folder / name
+        if path.is_file():
+            return path
+    raise FileNotFoundError("cannot find %s/%s beside scripts/ or in .feature-flow/" % (folder, name))
+
+
+def _body(path):
+    text = Path(path).read_text(encoding="utf-8")
+    if text.startswith("---\n"):
+        parts = text.split("\n---\n", 1)
+        if len(parts) == 2:
+            text = parts[1]
+    return text.strip("\n")
+
+
+def build(phase, scripts, feature, ticket, num, sha):
+    role = _body(find_file(scripts, "agents", ROLES[phase]))
+    guide = _body(find_file(scripts, "guides", GUIDES[phase]))
+    for placeholder, value in (("<feature>", feature), ("<NN>", num), ("<ticket>", ticket), ("<sha>", sha),
+                               ("<base>", sha), ("<base-commit>", sha), ("<start-commit>", sha)):
+        guide = guide.replace(placeholder, value)
+    fresh = ("Run `git log` and `git status` yourself before you start: a git snapshot taken when your "
+             "session began can be stale.")
+    if phase == "build":
+        task = ("Your task: build ticket %s of the feature `%s`, in auto mode (`%s auto %s`). The ticket is `%s`. "
+                "The work starts at commit `%s`.\n%s\nWhen you are done, reply with what you built and the "
+                "commit. Do not review your own work." % (num, feature, feature, num, ticket, sha, fresh))
+        intro = "The build guide follows. Follow it exactly."
+    else:
+        task = ("Your task: review ticket %s of the feature `%s` (`%s %s %s`). The ticket is `%s`, and the work "
+                "started at commit `%s`.\n%s\nDo not edit any file or create a commit. Your final reply must end "
+                "with exactly `REVIEW: PASS` or `REVIEW: FAIL`." % (num, feature, feature, num, sha, ticket, sha, fresh))
+        intro = "The review guide follows. Follow it exactly."
+    return "\n\n".join([role, "---", intro, guide, "---", task]) + "\n"

feature_flow/state.py

@@ -0,0 +1,75 @@
+"""The conductor's state and log, kept in .feature-flow/state/ at the top of the worktree.
+
+Not under .git: a normal Codex session cannot write there, and an unattended Claude session is
+refused there. The folder ignores itself (its .gitignore is `*`), so it never dirties the tree.
+The state file is key=value lines. It is parsed as plain text, never run as code.
+"""
+
+import shutil
+import time
+from pathlib import Path
+
+STATE_DIR = Path(".feature-flow") / "state"
+KINDS = ("state", "log", "findings")
+
+
+def state_dir(top):
+    """The state folder under the worktree top, created with its ignore rule on first use."""
+    path = Path(top) / STATE_DIR
+    path.mkdir(parents=True, exist_ok=True)
+    ignore = path / ".gitignore"
+    if not ignore.is_file():
+        ignore.write_text("*\n", encoding="utf-8")
+    return path
+
+
+def file_path(folder, feature, kind):
+    return Path(folder) / ("flow-%s.%s" % (feature, kind))
+
+
+def state_path(folder, feature):
+    return file_path(folder, feature, "state")
+
+
+def log_path(folder, feature):
+    return file_path(folder, feature, "log")
+
+
+def migrate(old_folder, new_folder, feature):
+    """Carry a run an earlier version kept under .git into the new folder, owner included, so the
+    owning session keeps its token. Only when the new folder has no state for the feature yet.
+    The state file is copied last, so a half-done copy is retried. The old files are left alone."""
+    if old_folder is None or state_path(new_folder, feature).is_file():
+        return False
+    if not state_path(old_folder, feature).is_file():
+        return False
+    for kind in reversed(KINDS):
+        old = file_path(old_folder, feature, kind)
+        if old.is_file():
+            shutil.copyfile(str(old), str(file_path(new_folder, feature, kind)))
+    return True
+
+
+def load(path):
+    data = {}
+    path = Path(path)
+    if not path.is_file():
+        return data
+    for line in path.read_text(encoding="utf-8").splitlines():
+        key, sep, value = line.partition("=")
+        if sep and key.strip():
+            data[key.strip()] = value
+    return data
+
+
+def save(path, data):
+    path = Path(path)
+    lines = ["%s=%s" % (key, str(value).replace("\n", " ")) for key, value in data.items()]
+    tmp = path.with_name(path.name + ".tmp")
+    tmp.write_text("\n".join(lines) + "\n", encoding="utf-8")
+    tmp.replace(path)
+
+
+def log(path, num, event):
+    with open(path, "a", encoding="utf-8") as handle:
+        handle.write("%s,%s,%s\n" % (time.strftime("%H:%M:%S"), num or "-", event))