nobrainer-tech-flow 0.0.0-stage → 2.4.0

package/scripts/install.py

@@ -0,0 +1,600 @@
+#!/usr/bin/env python3
+"""Install, preview or undo nobrainer-tech-flow for one client with one command.
+
+Every run is a dry run until --apply. The skills are linked and the managed
+instruction block is written by the same helpers as the manual and guided setups,
+and --undo uses the guided setup's rollback state (as scripts/install.sh does), so
+every path reverses the same way. This command never grants a standing authorization.
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib.util
+import os
+import re
+import shlex
+import subprocess
+import sys
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import NoReturn
+
+
+ROOT = Path(__file__).resolve().parents[1]
+GUIDED = ROOT / "scripts" / "recommend_flow_setup.py"
+INSTALL_SKILLS = ROOT / "scripts" / "install_skills.py"
+PERSONALIZATION = ROOT / "scripts" / "install_personalization.py"
+GUARDS = ROOT / "scripts" / "install_guards.py"
+# The guided setup wants a repository link for context; this command reads none.
+REPO_URL = "https://github.com/nobrainer-tech/nobrainer-tech-flow"
+LABELS = {
+    "claude": "Claude Code",
+    "codex": "Codex",
+    "opencode": "OpenCode",
+    "copilot": "GitHub Copilot CLI",
+}
+# The variable each client reads to find its configuration.
+VARIABLES = {"claude": "CLAUDE_CONFIG_DIR", "codex": "CODEX_HOME", "opencode": "XDG_CONFIG_HOME"}
+PYTHON = "py -3" if os.name == "nt" else "python3"
+# Lines of a helper's output that explain why it stopped or need the reader's eye.
+PROBLEM = re.compile(
+    r"^(ERROR|HINT|PRESERVED|WARNING|NOTE|CONFLICT\w*|LEGACY\w*|UNMAPPED_CONFLICT|"
+    r"MIGRATE\w*|ROLLBACK\w*|BACKUP_PRESERVED|INPUT_REQUIRED): "
+)
+KEPT = re.compile(r"^(KEPT_OPTIONS|NOTE|WARNING|HINT|LEGACY_STATE_\w+|BACKUP_PRESERVED): ")
+UNDO_NOTE = re.compile(r"^(PRESERVED|NOTE|WARNING|HINT): ")
+# The helpers name their own flags; this command has others for the same thing.
+TRANSLATIONS = (
+    ("--rollback --apply", "--undo --apply"),
+    ("rerun with --migrate-legacy --apply", "migrate it first, as the hint below says"),
+)
+CONFLICT_HINT = (
+    "a target above exists and is not a link to this checkout. Inspect it and move it away if "
+    f"it is yours to remove, or install the other skills one by one with {PYTHON} "
+    "scripts/install_skills.py --skill (docs/INSTALL.md)."
+)
+OVERRIDE_HINT = (
+    "Codex reads AGENTS.override.md instead of AGENTS.md; remove or empty that file and rerun, "
+    f"or write to it on purpose with {PYTHON} scripts/install_personalization.py --client codex "
+    "--path <file>."
+)
+
+
+class Refused(Exception):
+    """A helper refused; its reason is already printed and this is the exit code."""
+
+
+@dataclass(frozen=True)
+class Context:
+    client: str
+    apply: bool
+    home: Path
+    home_args: tuple[str, ...]
+    skills: Path
+    guided: object
+    # "NAME=value" when the client's own variable chose the locations.
+    variable: str | None = None
+
+    @property
+    def label(self) -> str:
+        return LABELS[self.client]
+
+    def command(self, *flags: str) -> str:
+        """The command that continues this run, keeping an explicit --home."""
+
+        parts = [PYTHON, "scripts/install.py", "--client", self.client, *flags]
+        if self.home_args:
+            parts += ["--home", quote(self.home_args[1])]
+        return " ".join(parts)
+
+    def variable_note(self) -> str | None:
+        if not self.variable:
+            return None
+        return f"NOTE: this setup follows {self.variable}; keep it set when you undo it."
+
+
+def quote(value: str) -> str:
+    return subprocess.list2cmdline([value]) if os.name == "nt" else shlex.quote(value)
+
+
+def unique(lines: list[str]) -> list[str]:
+    """The lines in order, each once: the guided setup can run a helper twice."""
+
+    return list(dict.fromkeys(lines))
+
+
+def load_module(name: str, path: Path):
+    spec = importlib.util.spec_from_file_location(name, path)
+    if spec is None or spec.loader is None:
+        raise ValueError(f"cannot load {path}")
+    module = importlib.util.module_from_spec(spec)
+    # dataclasses resolve string annotations through sys.modules.
+    sys.modules[spec.name] = module
+    try:
+        spec.loader.exec_module(module)
+    except BaseException:
+        sys.modules.pop(spec.name, None)
+        raise
+    return module
+
+
+def load_guided():
+    """The guided setup owns the client paths, the skill list and the rollback state."""
+
+    return load_module("_flow_guided_setup", GUIDED)
+
+
+def guards(args: argparse.Namespace) -> int:
+    """The optional Claude Code guards; scripts/install_guards.py owns them."""
+
+    if args.client != "claude":
+        print(f"UNSUPPORTED: the Flow guards exist only for Claude Code, not {LABELS[args.client]}.")
+        return 3
+    if os.name == "nt":
+        print("UNSUPPORTED: the Flow guards are POSIX-only in this version.")
+        return 3
+    module = load_module("_flow_install_guards", GUARDS)
+    home = Path(os.path.abspath(args.home.expanduser())) if args.home is not None else None
+    rerun = f"{PYTHON} scripts/install.py --client claude --guards {{flags}}"
+    if home is not None:
+        rerun += f" --home {quote(str(home))}"
+    try:
+        return module.run(args.apply, args.undo, home, rerun)
+    except module.Refused as refused:
+        print(f"REFUSED: {refused}; nothing was changed", file=sys.stderr)
+        return 3
+
+
+def guards_note(ctx: Context) -> str | None:
+    """A reminder that an undo leaves the guards, which then do nothing, in settings.json."""
+
+    if ctx.client != "claude" or os.name == "nt":
+        return None
+    module = load_module("_flow_install_guards", GUARDS)
+    settings, guard = module.locations(ctx.home if ctx.home_args else None)
+    if not module.installed(settings, guard):
+        return None
+    return (
+        f"NOTE: the optional Flow guards stay in {settings}; remove them with "
+        f"{ctx.command('--guards', '--undo', '--apply')}"
+    )
+
+
+def run(command: list[str]) -> tuple[int, str, str]:
+    # The helpers write UTF-8 whatever the console code page is, and must never ask.
+    result = subprocess.run(
+        command,
+        cwd=ROOT,
+        encoding="utf-8",
+        errors="replace",
+        capture_output=True,
+        check=False,
+        stdin=subprocess.DEVNULL,
+    )
+    return result.returncode, result.stdout, result.stderr
+
+
+def translate(text: str) -> str:
+    for helper_words, own_words in TRANSLATIONS:
+        text = text.replace(helper_words, own_words)
+    return text
+
+
+def refuse(code: int, out: str, err: str, hint: str | None = None) -> NoReturn:
+    for line in unique(out.splitlines()):
+        if PROBLEM.match(line):
+            print(translate(line), file=sys.stderr)
+    if err.strip():
+        print(translate(err.rstrip()), file=sys.stderr)
+    if hint:
+        print(f"HINT: {hint}", file=sys.stderr)
+    raise Refused(code)
+
+
+def git(*arguments: str) -> str | None:
+    try:
+        result = subprocess.run(
+            ["git", *arguments],
+            cwd=ROOT,
+            encoding="utf-8",
+            errors="replace",
+            capture_output=True,
+            check=False,
+            timeout=15,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    return result.stdout.strip() if result.returncode == 0 else None
+
+
+def source_line() -> str:
+    version = (ROOT / "skills" / "nobrainer-tech-flow" / "VERSION").read_text(encoding="utf-8").strip()
+    commit = git("rev-parse", "--short", "HEAD")
+    if not commit:
+        return f"nobrainer-tech-flow {version}"
+    changed = git("status", "--porcelain", "--untracked-files=no")
+    return f"nobrainer-tech-flow {version} (commit {commit}{', local changes' if changed else ''})"
+
+
+def nearest_existing(path: Path) -> Path | None:
+    for candidate in (path, *path.parents):
+        if candidate.is_dir():
+            return candidate
+    return None
+
+
+def symlinks_available(where: Path | None = None) -> bool:
+    """Whether this account can create directory links in WHERE (default: the temp folder)."""
+
+    try:
+        with tempfile.TemporaryDirectory(dir=where) as scratch:
+            target = Path(scratch) / "target"
+            target.mkdir()
+            os.symlink(target, Path(scratch) / "link", target_is_directory=True)
+    except (OSError, NotImplementedError):
+        return False
+    return True
+
+
+def symlink_help(where: Path | None = None) -> str:
+    place = f" in {where}" if where else ""
+    return (
+        f"ERROR: this machine cannot create symbolic links{place}, which this command needs.\n"
+        "HINT: on Windows turn on Developer Mode (Settings > System > For developers) or run "
+        "from an elevated shell, then rerun. To copy the skills instead, see docs/INSTALL.md "
+        "(Windows)."
+    )
+
+
+def plan_skills(ctx: Context) -> tuple[int, int]:
+    """Dry-run the skill install: (skills to link, skills already linked)."""
+
+    code, out, err = run(
+        [sys.executable, str(INSTALL_SKILLS), "--client", ctx.client, "--dest", str(ctx.skills)]
+    )
+    if code:
+        hint = None
+        if code == 3 and "legacy symlink detected" in err:
+            hint = (
+                "an entry above comes from an earlier layout of these skills. Migrate it with "
+                f"{PYTHON} scripts/install_skills.py --client {ctx.client} --dest "
+                f"{quote(str(ctx.skills))} --migrate-legacy --apply (docs/INSTALL.md, Conflict "
+                "and migration behavior), then run this again."
+            )
+        elif code == 3:
+            hint = CONFLICT_HINT
+        refuse(code, out, err, hint)
+    actions = [line.split(":", 1)[0] for line in out.splitlines()]
+    to_link = actions.count("SYMLINK")
+    if to_link and not symlinks_available():
+        print(symlink_help(), file=sys.stderr)
+        raise Refused(2)
+    return to_link, actions.count("KEEP")
+
+
+def plan_instructions(ctx: Context) -> list[str]:
+    code, out, err = run(
+        [
+            sys.executable,
+            str(PERSONALIZATION),
+            "--client",
+            ctx.client,
+            *ctx.home_args,
+            "--keep-options",
+        ]
+    )
+    if code:
+        refuse(
+            code,
+            out,
+            err,
+            OVERRIDE_HINT if "takes precedence over" in out + err else None,
+        )
+    return [line for line in out.splitlines() if not line.startswith("DRY_RUN:")]
+
+
+def guided_command(ctx: Context, *extra: str) -> list[str]:
+    return [
+        sys.executable,
+        str(GUIDED),
+        "--repo-url",
+        REPO_URL,
+        "--offline",
+        "--client",
+        ctx.client,
+        *ctx.home_args,
+        *extra,
+    ]
+
+
+def every_skill(ctx: Context) -> tuple[str, ...]:
+    # Every skill is selected; the answers only feed the recommendations this run ignores.
+    return (
+        "--work-profile",
+        "software-development",
+        "--goal",
+        "Install every nobrainer-tech-flow skill",
+        "--tools",
+        ctx.label,
+        "--existing-setup",
+        "not inspected",
+        "--selection",
+        ",".join(item.id for item in ctx.guided.ITEMS),
+    )
+
+
+def read_record(ctx: Context) -> dict[str, object] | None:
+    """The setup recorded for this client, as the guided setup reads it."""
+
+    guided = ctx.guided
+    for path in (guided.state_path(ctx.home, None, ctx.client), guided.legacy_state_path(ctx.home, None)):
+        if path is not None and path.is_file() and not path.is_symlink():
+            try:
+                return guided.read_state_file(path)
+            except (OSError, ValueError):
+                return None
+    return None
+
+
+def unrecorded_path(ctx: Context) -> Path | None:
+    """Where this client's setup record would be, when no record exists at all.
+
+    Neither this client's record nor the older single-client one may be there, not even
+    as a link: anything that is there is a record to read, or to refuse. A path that cannot
+    be checked, because a folder on the way cannot be searched, raises OSError: a record may
+    be there, so it is not the same as none.
+    """
+
+    guided = ctx.guided
+    paths = (guided.state_path(ctx.home, None, ctx.client), guided.legacy_state_path(ctx.home, None))
+    for path in paths:
+        if path is None:
+            continue
+        try:
+            path.lstat()
+        except (FileNotFoundError, NotADirectoryError):
+            continue
+        return None
+    return paths[0]
+
+
+def install(ctx: Context) -> int:
+    to_link, kept = plan_skills(ctx)
+    instructions = plan_instructions(ctx)
+    # The guided setup's own dry run checks the recorded setup, the paths and the
+    # target, so the preview refuses whatever --apply would refuse.
+    code, out, err = run(guided_command(ctx, *every_skill(ctx)))
+    if code:
+        refuse(code, out, err)
+    if not ctx.apply:
+        print(f"{source_line()} for {ctx.label}")
+        print(f"SKILLS: {to_link} to link into {ctx.skills} ({kept} already linked)")
+        for line in unique(instructions):
+            print(line)
+        note = ctx.variable_note()
+        if note:
+            print(note)
+        print(f"NO_CHANGES: preview only; install with: {ctx.command('--apply')}")
+        return 0
+    where = nearest_existing(ctx.skills)
+    if to_link and not symlinks_available(where):
+        print(symlink_help(where), file=sys.stderr)
+        raise Refused(2)
+    earlier = read_record(ctx) or {}
+    code, out, err = run(guided_command(ctx, *every_skill(ctx), "--apply"))
+    if code:
+        if os.name == "nt" and re.search(r"WinError 1314|privilege", out + err, re.IGNORECASE):
+            print(symlink_help(), file=sys.stderr)
+        refuse(code, out, err)
+    record = read_record(ctx) or {}
+    profile = record.get("profile") or {}
+    linked = len(ctx.guided.installed_ids(ctx.skills))
+    # New links and a written instruction file are what a client has to be restarted for.
+    # The personalization helper prints APPLIED only for a file it wrote.
+    written = re.search(r"^APPLIED: ", out, re.MULTILINE) is not None
+    changed = bool(to_link) or written
+    if changed:
+        print(f"INSTALLED: {source_line()} for {ctx.label}")
+    else:
+        print(f"UP TO DATE: {source_line()} is already installed for {ctx.label}; nothing changed")
+    print(f"SKILLS: {linked} linked in {ctx.skills} ({to_link} new)")
+    if profile.get("target"):
+        backup = profile.get("backup")
+        if written and re.search(r"^UPDATE: ", out, re.MULTILINE):
+            # A block of an earlier version was replaced. This run's backup holds the file as
+            # it was just before; the recorded one is the file from before the setup.
+            made = re.search(r"^BACKUP: (.+)$", out, re.MULTILINE)
+            print(
+                f"INSTRUCTIONS: {profile['target']}: managed block updated to this version's text; "
+                "the rest of the file is kept as it is" + (f" (backup: {made.group(1)})" if made else "")
+            )
+        elif written:
+            print(f"INSTRUCTIONS: {profile['target']}" + (f" (backup: {backup})" if backup else ""))
+        else:
+            print(f"INSTRUCTIONS: {profile['target']} already has the managed block; left as it is")
+    else:
+        print("INSTRUCTIONS: inherited from the Codex global instructions; nothing written here")
+    for line in unique(out.splitlines()):
+        if KEPT.match(line):
+            print(line)
+    recorded = (earlier.get("profile") or {}).get("written_sha256")
+    if not changed and earlier and profile.get("written_sha256") not in (None, recorded):
+        print("RECORD: updated to the instruction file as it is now, so an undo keeps your edits outside the block")
+    print(f"UNDO: {ctx.command('--undo', '--apply')}")
+    note = ctx.variable_note()
+    if note:
+        print(note)
+    if changed:
+        print(
+            f"NEXT: restart {ctx.label}, then give it one small task with a checkable result "
+            "(docs/TRY_IT.md)."
+        )
+    return 0
+
+
+def undo(ctx: Context) -> int:
+    try:
+        missing = unrecorded_path(ctx)
+    except OSError as exc:
+        print(f"ERROR: cannot check {exc.filename}: {exc.strerror}; nothing was changed", file=sys.stderr)
+        print("HINT: give this account access to the folders on that path, then undo again", file=sys.stderr)
+        return 3
+    if missing is not None:
+        # A second undo, or an undo before any setup: nothing is recorded, so nothing is
+        # to be reversed, and nothing is written.
+        print(
+            f"NOTHING TO UNDO: no setup is recorded for {ctx.label} (looked for {missing}); "
+            "nothing was changed"
+        )
+        return 0
+    record = read_record(ctx)
+    code, out, err = run(guided_command(ctx, "--rollback", *(("--apply",) if ctx.apply else ())))
+    destination = str(record["destination"]) if record else str(ctx.skills)
+    readback = re.search(r"^ROLLBACK_READBACK: removed=([^;\n]*);", out, re.MULTILINE)
+    if code == 3 and readback and re.search(r"; profile=preserved$", out, re.MULTILINE):
+        # The instruction file changed since the setup: the links are gone, the file stays.
+        removed = [name for name in readback.group(1).split(",") if name not in ("", "none")]
+        print(f"PARTLY UNDONE: nobrainer-tech-flow for {ctx.label}")
+        print(f"SKILLS: {len(removed)} unlinked from {destination}")
+        for line in unique(out.splitlines()):
+            if UNDO_NOTE.match(line):
+                print(line)
+        print(f"NEXT: restart {ctx.label} to drop the skills.")
+        return code
+    if code:
+        print(translate(out), end="")
+        print(translate(err), end="", file=sys.stderr)
+        return code
+    created = list(record.get("created_skills", [])) if record else []
+    directories = list(record.get("created_dirs", [])) if record else []
+    profile = (record or {}).get("profile") or {}
+    target = profile.get("target")
+    backup = profile.get("backup")
+    if not ctx.apply:
+        print(f"UNDO_PLAN: unlink {len(created)} skills from {destination}")
+        if re.search(r"^PRESERVED: personalization changed since setup", out, re.MULTILINE):
+            # The file stays as it is, and so do the folders; the note below says why.
+            target, directories = None, []
+        kept = re.search(r"^INSTRUCTIONS_KEPT: (.+)$", out, re.MULTILINE)
+        if kept:
+            print(f"INSTRUCTIONS: {kept.group(1)}")
+        elif target and backup:
+            print(
+                f"INSTRUCTIONS: {target}: put the managed block back as it was before the setup "
+                f"(from {backup}); later edits outside the block stay"
+            )
+        elif target:
+            print(f"INSTRUCTIONS: {target}: remove the managed block")
+        for folder in sorted(directories, key=lambda item: len(Path(item).parts), reverse=True):
+            print(f"FOLDER: {folder}: removed if it is still empty; the setup created it")
+        for line in unique(out.splitlines()):
+            if UNDO_NOTE.match(line):
+                print(line)
+        note = ctx.variable_note()
+        if note:
+            print(note)
+        print(f"NO_CHANGES: preview only; undo with: {ctx.command('--undo', '--apply')}")
+        return 0
+    removed = [name for name in readback.group(1).split(",") if name not in ("", "none")] if readback else []
+    print(f"UNDONE: nobrainer-tech-flow for {ctx.label}")
+    print(f"SKILLS: {len(removed)} unlinked from {destination}")
+    kept = re.search(r"^INSTRUCTIONS_KEPT: (.+)$", out, re.MULTILINE)
+    if kept:
+        print(f"INSTRUCTIONS: {kept.group(1)}")
+    elif target:
+        if any(line.startswith("RESTORED: ") for line in out.splitlines()):
+            print(f"INSTRUCTIONS: {target} is back as it was before the setup (backup kept: {backup})")
+        elif not Path(str(target)).exists():
+            print(f"INSTRUCTIONS: {target} removed; the setup had created it")
+        else:
+            print(f"INSTRUCTIONS: managed block removed from {target}; the rest of the file is kept as it is now")
+    for folder in re.findall(r"^REMOVED_DIR: (.+)$", out, re.MULTILINE):
+        print(f"FOLDER: removed the empty folder {folder}")
+    for line in unique(out.splitlines()):
+        if UNDO_NOTE.match(line):
+            print(line)
+    note = guards_note(ctx)
+    if note:
+        print(note)
+    print(f"NEXT: restart {ctx.label} to drop the skills.")
+    return 0
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description=(
+            "Link every nobrainer-tech-flow skill and add the managed instruction block for "
+            "one client. Without --apply this only previews."
+        ),
+        epilog=(
+            "Without Python: scripts/install.sh takes the same flags. Subsets, copy installs, "
+            "the shared agents folder and other clients: docs/INSTALL.md."
+        ),
+    )
+    parser.add_argument("--client", choices=tuple(LABELS), required=True)
+    parser.add_argument(
+        "--home",
+        type=Path,
+        help="profile home for the documented default locations; when omitted, "
+        "CLAUDE_CONFIG_DIR, CODEX_HOME and XDG_CONFIG_HOME are honoured",
+    )
+    parser.add_argument("--apply", action="store_true", help="write the changes; the default is a preview")
+    parser.add_argument(
+        "--undo",
+        action="store_true",
+        help="reverse the setup this command, scripts/install.sh or the guided setup recorded "
+        "(add --apply to do it)",
+    )
+    parser.add_argument(
+        "--guards",
+        action="store_true",
+        help="Claude Code only: add the optional hooks that ask before risky commands and for a "
+        "proof line, instead of installing the skills; with --undo remove them (docs/INSTALL.md)",
+    )
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            # Piped output on Windows uses the ANSI code page, which cannot print every
+            # character of a path.
+            stream.reconfigure(encoding="utf-8", errors="replace")
+        except (AttributeError, ValueError):
+            pass
+    args = parse_args(argv)
+    try:
+        if args.guards:
+            return guards(args)
+        guided = load_guided()
+        # An explicit --home selects the documented defaults under it and ignores the
+        # environment, exactly as the helpers do. They run from the checkout, so a
+        # relative path would land inside it.
+        variable = None
+        if args.home is not None:
+            home = Path(os.path.abspath(args.home.expanduser()))
+            environ: object = {}
+            home_args = ("--home", str(home))
+        else:
+            if os.name != "nt" and os.environ.get("HOME") == "":
+                raise ValueError("HOME is set but empty")
+            home, environ, home_args = Path.home(), os.environ, ()
+            if not home.is_absolute():
+                raise ValueError(f"the home directory must be an absolute path, not {str(home)!r}")
+            name = VARIABLES.get(args.client)
+            if name and os.environ.get(name):
+                variable = f"{name}={os.environ[name]}"
+        skills = guided.skills_destination(args.client, home, environ).expanduser().resolve()
+        ctx = Context(args.client, args.apply, home, home_args, skills, guided, variable)
+        return undo(ctx) if args.undo else install(ctx)
+    except Refused as refused:
+        return refused.args[0]
+    except (OSError, RuntimeError, ValueError) as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())