forgedock 1.27.0 → 1.28.0

package/scripts/symbol-move.py

@@ -0,0 +1,383 @@
+#!/usr/bin/env python3
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# symbol-move.py: codemod mover for refactor:split (forge#4210, #4196). Moves groups of top-level symbols out of one
+# Python module into a sibling package and leaves a re-export shim at the old path. A CST tool (libcst) copies every
+# moved statement byte-for-byte; no LLM, no network, nothing is retyped.
+#
+# Usage: python3 scripts/symbol-move.py --src <file.py> --plan <plan.json> [--package <name>] [--extend] [--dry-run]
+#   plan: {"<module>": ["<top-level symbol>", ...], ...}, names as scripts/symbol-index.py reports them.
+#   --package defaults to <stem>_parts, created next to --src. --extend (a chain step of a large split, forge#4211) adds
+#   the plan's modules to an existing package dir instead: its __init__.py is left untouched (created when absent) and a
+#   module file that already exists in it refuses. Without --extend an existing package path refuses.
+# Output (stdout, one JSON object):
+#   ok:      {"status":"ok","package":"<dotted package>","modules":{module:[symbols]},"shim":"<src path>"}
+#   refused: {"status":"refused","reason":"..."}
+# Result: <package>/__init__.py (empty) and <package>/<module>.py per plan entry, each holding, in order, the
+#   source's `from __future__` imports, the source's module-level import statements its symbols use (verbatim;
+#   relative imports gain one level), `from .<other> import ...` for symbols moved to sibling modules, then the
+#   moved statements verbatim (leading comments included) in source order. --src keeps every unmoved statement
+#   verbatim and gains `from <dotted package>.<module> import (...)` re-exports for every moved name, private ones
+#   included, at the position of the first moved statement. Every changed line is a moved block or an import line,
+#   so scripts/refactor-verify.sh can prove the move.
+# Refuses (no file touched) when libcst is not importable, the source does not parse, or the plan is invalid:
+#   unknown or non-top-level symbol, a symbol listed twice, a statement split across modules, a bad or colliding
+#   module name, an existing package path, a moved symbol that needs a name staying in --src, a name bound by both
+#   moved and kept statements, module-identity globals (__name__, globals(), ...) in moved code, a star import,
+#   or an import cycle between the new modules.
+# Writes are atomic: every file is built in memory, written to a temp file and os.replace'd in, the shim last.
+# Exit: 0 ok | 2 usage or missing file | 3 refused.
+
+import json
+import keyword
+import os
+import shutil
+import sys
+import tempfile
+
+MODULE_GLOBALS = {"__name__", "__file__", "__spec__", "__package__", "__loader__", "__path__", "__builtins__",
+                  "__cached__", "globals", "vars"}
+
+
+class Refused(Exception):
+    pass
+
+
+def emit(obj):
+    sys.stdout.write(json.dumps(obj, sort_keys=True, separators=(",", ":")) + "\n")
+
+
+def usage():
+    sys.stderr.write("usage: symbol-move.py --src <file.py> --plan <plan.json> [--package <name>] [--extend] [--dry-run]\n")
+    return 2
+
+
+def parse_args(argv):
+    opts, i = {"package": None, "dry_run": False, "extend": False}, 0
+    while i < len(argv):
+        a = argv[i]
+        if a == "--dry-run":
+            opts["dry_run"] = True
+            i += 1
+        elif a == "--extend":
+            opts["extend"] = True
+            i += 1
+        elif a in ("--src", "--plan", "--package") and i + 1 < len(argv):
+            opts[a[2:]] = argv[i + 1]
+            i += 2
+        else:
+            return None
+    return opts if opts.get("src") and opts.get("plan") else None
+
+
+def dotted_package(directory):
+    """Dotted import path of a directory, walking up while __init__.py exists ('' for a plain directory)."""
+    parts, d = [], os.path.abspath(directory)
+    while os.path.isfile(os.path.join(d, "__init__.py")):
+        parts.append(os.path.basename(d))
+        parent = os.path.dirname(d)
+        if parent == d:
+            break
+        d = parent
+    return ".".join(reversed(parts))
+
+
+def load_plan(path):
+    try:
+        with open(path, encoding="utf-8") as fh:
+            plan = json.load(fh)
+    except (OSError, ValueError) as e:
+        raise Refused("plan is not readable JSON: %s" % e)
+    if not isinstance(plan, dict) or not plan:
+        raise Refused("plan must be a non-empty object {module: [symbols]}")
+    for mod, names in plan.items():
+        if not isinstance(names, list) or not names or not all(isinstance(n, str) for n in names):
+            raise Refused("plan entry %r must be a non-empty list of symbol names" % mod)
+        if not mod.isidentifier() or keyword.iskeyword(mod) or mod == "__init__":
+            raise Refused("module name %r is not a valid identifier" % mod)
+    return plan
+
+
+def build(cst, src, plan, package, extend=False):
+    from libcst.metadata import GlobalScope, MetadataWrapper, ScopeProvider
+
+    with open(src, "rb") as fh:
+        raw = fh.read()
+    try:
+        module = cst.parse_module(raw)
+    except Exception as e:  # libcst.ParserSyntaxError and decode errors
+        raise Refused("source does not parse: %s" % str(e).splitlines()[0])
+    body = list(module.body)
+
+    def is_import_line(stmt):
+        return isinstance(stmt, cst.SimpleStatementLine) and all(
+            isinstance(s, (cst.Import, cst.ImportFrom)) for s in stmt.body)
+
+    def is_future(stmt):
+        return is_import_line(stmt) and all(
+            isinstance(s, cst.ImportFrom) and isinstance(s.module, cst.Name) and s.module.value == "__future__"
+            for s in stmt.body)
+
+    def target_names(t):
+        if isinstance(t, cst.Name):
+            return [t.value]
+        if isinstance(t, (cst.Tuple, cst.List)) and all(isinstance(e.value, cst.Name) for e in t.elements):
+            return [e.value.value for e in t.elements]
+        return None
+
+    # movable top-level statements: def, class, or a line of plain assignments; index -> names it binds
+    movable = {}
+    for idx, stmt in enumerate(body):
+        if isinstance(stmt, (cst.FunctionDef, cst.ClassDef)):
+            movable[idx] = [stmt.name.value]
+        elif isinstance(stmt, cst.SimpleStatementLine) and all(
+                isinstance(s, (cst.Assign, cst.AnnAssign)) for s in stmt.body):
+            names, ok = [], True
+            for s in stmt.body:
+                targets = [t.target for t in s.targets] if isinstance(s, cst.Assign) else [s.target]
+                for t in targets:
+                    got = target_names(t)
+                    if got is None:
+                        ok = False
+                    else:
+                        names.extend(got)
+            if ok:
+                movable[idx] = names
+        if is_import_line(stmt) and any(isinstance(s, cst.ImportFrom) and isinstance(s.names, cst.ImportStar)
+                                        for s in stmt.body):
+            raise Refused("source has a star import at line %d; names cannot be resolved" % (idx + 1))
+
+    symbol_stmt = {}
+    for idx, names in movable.items():
+        for n in names:
+            symbol_stmt.setdefault(n, idx)
+
+    # plan -> statement index -> module
+    assigned, stmt_module = {}, {}
+    for mod, names in plan.items():
+        for n in names:
+            if n in assigned:
+                raise Refused("symbol %r is listed twice (%s, %s)" % (n, assigned[n], mod))
+            assigned[n] = mod
+            if "." in n:
+                raise Refused("%r is not a top-level symbol; only top-level symbols move" % n)
+            if n not in symbol_stmt:
+                raise Refused("unknown symbol %r: not a top-level def, class or assignment in %s" % (n, src))
+            idx = symbol_stmt[n]
+            if stmt_module.setdefault(idx, mod) != mod:
+                raise Refused("symbol %r shares a statement with symbols planned for another module" % n)
+    for idx, mod in stmt_module.items():
+        missing = [n for n in movable[idx] if assigned.get(n) != mod]
+        if missing:
+            raise Refused("statement binding %s also binds %s, which the plan does not move with it"
+                          % (", ".join(sorted(set(movable[idx]) - set(missing))), ", ".join(missing)))
+
+    # node -> owning top-level statement
+    owner = {}
+    for idx, stmt in enumerate(body):
+        stack = [stmt]
+        while stack:
+            node = stack.pop()
+            owner[id(node)] = idx
+            stack.extend(node.children)
+
+    wrapper = MetadataWrapper(module, unsafe_skip_copy=True)
+    scopes = wrapper.resolve(ScopeProvider)
+    gscope = next((s for s in scopes.values() if isinstance(s, GlobalScope)), None)
+    binders, users = {}, {}
+    if gscope is not None:
+        for a in gscope.assignments:
+            b = owner.get(id(a.node))
+            if b is None:
+                continue
+            binders.setdefault(a.name, set()).add(b)
+            for r in a.references:
+                u = owner.get(id(r.node))
+                if u is not None:
+                    users.setdefault(a.name, set()).add(u)
+
+    top_names = set(binders) | set(symbol_stmt)
+    for mod in plan:
+        if mod in top_names:
+            raise Refused("module name %r collides with a top-level name in %s" % (mod, src))
+
+    for name, bs in sorted(binders.items()):
+        mods = {stmt_module.get(b) for b in bs}
+        if len(mods) > 1:
+            where = sorted(m or "<kept>" for m in mods)
+            raise Refused("name %r is bound by statements going to different places (%s)" % (name, ", ".join(where)))
+
+    # identity-dependent globals in moved code would change meaning in a new module
+    for idx in sorted(stmt_module):
+        stack = [(body[idx], None)]
+        while stack:
+            node, parent = stack.pop()
+            if isinstance(node, cst.Name) and node.value in MODULE_GLOBALS and not (
+                    isinstance(parent, cst.Attribute) and parent.attr is node):
+                raise Refused("moved symbol %s uses module-identity global %r" % (movable[idx][0], node.value))
+            stack.extend((c, node) for c in node.children)
+
+    need_imports = {m: set() for m in plan}      # module -> import statement indexes
+    need_from = {m: {} for m in plan}            # module -> {other module: set(names)}
+    for name in sorted(users):
+        bs = binders.get(name, set())
+        for u in sorted(users[name]):
+            mod = stmt_module.get(u)
+            if mod is None or not bs:
+                continue
+            kept = [b for b in bs if b not in stmt_module and not is_import_line(body[b])]
+            if kept:
+                raise Refused("moved symbol %s (-> %s) needs %r, which stays in %s (line of statement %d)"
+                              % (movable[u][0], mod, name, src, min(kept) + 1))
+            other = stmt_module.get(next(iter(bs)))
+            if other is None:
+                need_imports[mod].update(bs)
+            elif other != mod:
+                need_from[mod].setdefault(other, set()).add(name)
+
+    # import cycles between the new modules
+    state = {}
+
+    def visit(m, path):
+        state[m] = 1
+        for o in sorted(need_from[m]):
+            if state.get(o) == 1:
+                raise Refused("plan creates an import cycle: %s" % " -> ".join(path[path.index(o):] + [o]))
+            if o not in state:
+                visit(o, path + [o])
+        state[m] = 2
+    for m in sorted(plan):
+        if m not in state:
+            visit(m, [m])
+
+    src_dir = os.path.dirname(os.path.abspath(src))
+    pkg_dir = os.path.join(src_dir, package)
+    if os.path.exists(pkg_dir + ".py") or (os.path.exists(pkg_dir) and not (extend and os.path.isdir(pkg_dir))):
+        raise Refused("package path already exists: %s" % pkg_dir)
+    if extend:
+        taken = [m for m in plan if os.path.exists(os.path.join(pkg_dir, m + ".py"))]
+        if taken:
+            raise Refused("module already exists in package %s: %s" % (pkg_dir, ", ".join(sorted(taken))))
+    base = dotted_package(src_dir)
+    dotted = (base + "." if base else "") + package
+
+    def code(stmt, strip_leading=False):
+        if strip_leading:
+            stmt = stmt.with_changes(leading_lines=())
+        return module.code_for_node(stmt)
+
+    def import_code(idx):
+        stmt = body[idx]
+        stmt = stmt.with_changes(body=[
+            s.with_changes(relative=[cst.Dot()] + list(s.relative))
+            if isinstance(s, cst.ImportFrom) and s.relative else s for s in stmt.body])
+        return code(stmt, strip_leading=True)
+
+    newline = module.default_newline
+
+    def from_import(target, names):
+        return "from %s import (%s%s)%s" % (target, newline, "".join("    %s,%s" % (n, newline) for n in names), newline)
+
+    futures = [i for i, s in enumerate(body) if is_future(s)]
+    order = sorted(plan, key=lambda m: min(i for i, mm in stmt_module.items() if mm == m))
+    files, modules_out = {}, {}
+    for mod in order:
+        moved = sorted(i for i, mm in stmt_module.items() if mm == mod)
+        head = [code(body[i], strip_leading=True) for i in futures]
+        head += [import_code(i) for i in sorted(need_imports[mod]) if i not in futures]
+        for other in sorted(need_from[mod], key=order.index):
+            names = sorted(need_from[mod][other], key=lambda n: (symbol_stmt[n], n))
+            head.append(from_import("." + other, names))
+        files[os.path.join(pkg_dir, mod + ".py")] = "".join(head) + "".join(code(body[i]) for i in moved)
+        modules_out[mod] = [n for i in moved for n in movable[i]]
+    if not os.path.exists(os.path.join(pkg_dir, "__init__.py")):
+        files[os.path.join(pkg_dir, "__init__.py")] = ""
+
+    first = min(stmt_module)
+    reexport = "".join(from_import("%s.%s" % (dotted, mod), modules_out[mod]) for mod in order)
+    shim_stmts = list(cst.parse_module(reexport).body)
+    blank = [ln for ln in body[first].leading_lines if ln.comment is None]
+    shim_stmts[0] = shim_stmts[0].with_changes(leading_lines=blank)
+    new_body = []
+    for idx, stmt in enumerate(body):
+        if idx == first:
+            new_body.extend(shim_stmts)
+        if idx not in stmt_module:
+            new_body.append(stmt)
+    shim = module.with_changes(body=new_body)
+    return {"files": files, "shim": shim.code, "encoding": module.encoding, "pkg_dir": pkg_dir,
+            "result": {"status": "ok", "package": dotted, "modules": modules_out, "shim": src}}
+
+
+def write_atomic(src, plan_out):
+    enc, pkg_dir = plan_out["encoding"], plan_out["pkg_dir"]
+    temps, created, placed = [], False, []
+    try:
+        if not os.path.isdir(pkg_dir):
+            os.mkdir(pkg_dir)
+            created = True
+        staged = []
+        for path, text in sorted(plan_out["files"].items()) + [(src, plan_out["shim"])]:
+            fd, tmp = tempfile.mkstemp(prefix=".symbol-move-", suffix=".tmp", dir=os.path.dirname(os.path.abspath(path)))
+            temps.append(tmp)
+            with os.fdopen(fd, "wb") as fh:
+                fh.write(text.encode(enc))
+            if path == src:
+                shutil.copymode(src, tmp)
+            staged.append((tmp, path))
+        for tmp, path in staged:  # shim last: until then --src is untouched
+            os.replace(tmp, path)
+            temps.remove(tmp)
+            if path != src:
+                placed.append(path)
+    except BaseException:
+        for tmp in temps:
+            try:
+                os.unlink(tmp)
+            except OSError:
+                pass
+        if created:
+            shutil.rmtree(pkg_dir, ignore_errors=True)
+        else:  # --extend: remove only the files this run added to the existing package
+            for path in placed:
+                try:
+                    os.unlink(path)
+                except OSError:
+                    pass
+        raise
+
+
+def main(argv):
+    opts = parse_args(argv)
+    if opts is None:
+        return usage()
+    src, plan_path = opts["src"], opts["plan"]
+    for p in (src, plan_path):
+        if not os.path.exists(p):
+            sys.stderr.write("symbol-move: no such file: %s\n" % p)
+            return 2
+    try:
+        import libcst as cst
+    except ImportError:
+        emit({"status": "refused",
+              "reason": "no codemod tool: libcst (or rope) not importable for %s" % sys.executable})
+        return 3
+    try:
+        if not src.endswith(".py") or not os.path.isfile(src):
+            raise Refused("source is not a .py file: %s" % src)
+        package = opts["package"] or os.path.splitext(os.path.basename(src))[0] + "_parts"
+        if not package.isidentifier() or keyword.iskeyword(package):
+            raise Refused("package name %r is not a valid identifier" % package)
+        out = build(cst, src, load_plan(plan_path), package, opts["extend"])
+    except Refused as r:
+        emit({"status": "refused", "reason": str(r)})
+        return 3
+    if not opts["dry_run"]:
+        write_atomic(src, out)
+    emit(out["result"])
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/scripts/symbol-move.test.sh

@@ -0,0 +1,168 @@
+#!/usr/bin/env bash
+# symbol-move.test.sh — cases for scripts/symbol-move.py (forge#4210).
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Builds a throwaway git repo from scripts/fixtures/symbol-move/gen_big.py (~3k-line module + unittest suite), moves
+# four symbol groups into pkg/big_parts/ and proves the move with scripts/refactor-verify.sh; then checks refusals and
+# the --extend chain step (forge#4211).
+# Interpreter with libcst: $SYMBOL_MOVE_PYTHON, else python3 if it has libcst, else `uv run --no-project --with libcst
+# python`. Without one the libcst cases are skipped; SYMBOL_MOVE_REQUIRE_LIBCST=1 turns that skip into a failure.
+set -uo pipefail
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SM="$HERE/symbol-move.py"; RV="$HERE/refactor-verify.sh"; GEN="$HERE/fixtures/symbol-move/gen_big.py"
+PASS=0; FAILN=0
+TMP="$(mktemp -d "${TMPDIR:-/tmp}/symbol-move-test.XXXXXX")"; trap 'rm -rf "$TMP"' EXIT
+ok() { PASS=$((PASS+1)); }
+bad() { FAILN=$((FAILN+1)); echo "FAIL: $1"; }
+eq() { if [ "$2" = "$3" ]; then ok; else bad "$1 (got: $2 want: $3)"; fi }
+q() { printf '%s' "$OUT" | jq -c "$1"; }
+run() { OUT="$("$@" 2>"$TMP/err")"; RC=$?; }
+export PYTHONDONTWRITEBYTECODE=1
+
+PYCMD=""
+if [ -n "${SYMBOL_MOVE_PYTHON:-}" ]; then
+  PYCMD="$SYMBOL_MOVE_PYTHON"
+elif python3 -c 'import libcst' >/dev/null 2>&1; then
+  PYCMD="python3"
+elif command -v uv >/dev/null 2>&1 && uv run --no-project --with libcst python -c 'import libcst' >/dev/null 2>&1; then
+  PYCMD="uv run --no-project --with libcst python"
+fi
+# shellcheck disable=SC2086 # PYCMD is a command line
+mover() { run $PYCMD "$SM" "$@"; }
+
+R="$TMP/repo"; B="$TMP/baseline.json"; P="$TMP/plan.json"
+TEST_CMD='python3 -m unittest discover -s tests -t .'
+g() { git -C "$R" -c user.name=t -c user.email=t@example.invalid "$@"; }
+mkdir -p "$R"; git init -q "$R"
+printf '__pycache__/\n' > "$R/.gitignore"
+python3 "$GEN" "$R" || bad "generator failed"
+g add -A && g commit -qm base && g tag base
+eq "fixture size >= 2500 lines" "$([ "$(wc -l < "$R/pkg/big.py")" -ge 2500 ] && echo yes || echo no)" yes
+SHA0="$(git -C "$R" hash-object pkg/big.py)"
+
+plan() { python3 -c 'import json,sys; print(json.dumps(json.loads(sys.argv[1])))' "$1" > "$2"; }
+FULL='{"consts":['"$(printf '"LIMIT_%02d",' $(seq 0 89))"'"_SEPARATOR"],
+ "helpers":['"$(for i in $(seq -w 0 89); do printf '"_scale_%s","compute_%s",' "$i" "$i"; done)"'"join_parts"],
+ "aio":['"$(printf '"fetch_%02d",' $(seq 0 28))"'"fetch_29"],
+ "models":['"$(printf '"Item_%02d",' $(seq 0 28))"'"Item_29"]}'
+plan "$FULL" "$P"
+
+# refused <label>: rc 3, status refused, a reason, and nothing changed in the repo
+refused() {
+  eq "$1: rc" "$RC" 3
+  eq "$1: status" "$(q '.status')" '"refused"'
+  eq "$1: has reason" "$(q '.reason|length>0')" true
+  eq "$1: tree untouched" "$(git -C "$R" status --porcelain)" ""
+  eq "$1: shim untouched" "$(git -C "$R" hash-object pkg/big.py)" "$SHA0"
+}
+
+# ---- 1. no codemod tool: stdlib-only interpreter (no site-packages) refuses before touching anything ----
+run python3 -I -S "$SM" --src "$R/pkg/big.py" --plan "$P"
+refused "no codemod tool"
+eq "no codemod tool: reason" "$(q '.reason|startswith("no codemod tool")')" true
+eq "no codemod tool: one JSON object" "$(printf '%s\n' "$OUT" | wc -l | tr -d ' ')" 1
+
+# ---- 2. usage ----
+python3 -I -S "$SM" >/dev/null 2>&1; eq "no args" "$?" 2
+python3 -I -S "$SM" --src "$R/pkg/missing.py" --plan "$P" >/dev/null 2>&1; eq "missing src" "$?" 2
+
+if [ -z "$PYCMD" ]; then
+  echo "symbol-move.test.sh: libcst cases skipped (no python with libcst; set SYMBOL_MOVE_PYTHON)"
+  [ "${SYMBOL_MOVE_REQUIRE_LIBCST:-}" = 1 ] && bad "libcst required (SYMBOL_MOVE_REQUIRE_LIBCST=1) but not available"
+else
+  # ---- 3. invalid plans refuse with no edits ----
+  plan '{"a":["compute_00","no_such_symbol"]}' "$TMP/p1.json"
+  mover --src "$R/pkg/big.py" --plan "$TMP/p1.json"; refused "unknown symbol"
+  eq "unknown symbol: reason" "$(q '.reason|contains("no_such_symbol")')" true
+  plan '{"a":["compute_00","LIMIT_00"],"b":["LIMIT_00"]}' "$TMP/p2.json"
+  mover --src "$R/pkg/big.py" --plan "$TMP/p2.json"; refused "symbol twice"
+  eq "symbol twice: reason" "$(q '.reason|contains("listed twice")')" true
+  plan '{"helpers":["_scale_00","compute_00"]}' "$TMP/p3.json"
+  mover --src "$R/pkg/big.py" --plan "$TMP/p3.json"; refused "depends on kept symbol"
+  eq "depends on kept symbol: reason" "$(q '.reason|contains("LIMIT_00")')" true
+  plan '{"a":["Item_00.label"]}' "$TMP/p4.json"
+  mover --src "$R/pkg/big.py" --plan "$TMP/p4.json"; refused "method"
+  plan '{"x":["Item_00","LIMIT_00","_SEPARATOR"],"y":["_scale_00","compute_00","join_parts"]}' "$TMP/p6.json"
+  mover --src "$R/pkg/big.py" --plan "$TMP/p6.json"; refused "import cycle"
+  eq "import cycle: reason" "$(q '.reason|contains("import cycle")')" true
+  plan '{"consts":["LIMIT_00"],"helpers":["_scale_00","compute_00"],"back":["_SEPARATOR"]}' "$TMP/p5.json"
+  mover --src "$R/pkg/big.py" --plan "$TMP/p5.json" --dry-run
+  eq "independent subset moves in dry-run" "$RC" 0
+  eq "dry-run writes nothing" "$(git -C "$R" status --porcelain)" ""
+  mkdir -p "$R/pkg/big_parts"; : > "$R/pkg/big_parts/keep.txt"
+  mover --src "$R/pkg/big.py" --plan "$P"
+  eq "existing package: reason" "$(q '.reason|contains("already exists")')" true
+  eq "existing package: rc" "$RC" 3
+  eq "existing package: kept" "$(ls "$R/pkg/big_parts")" keep.txt
+  rm -rf "$R/pkg/big_parts"
+  refused "existing package"
+
+  # ---- 4. full plan: package + import-only shim, proved by refactor-verify ----
+  run bash "$RV" baseline --root "$R" --target pkg/big.py --test-cmd "$TEST_CMD" --out "$B"
+  eq "baseline rc" "$RC" 0
+  eq "baseline counts" "$(jq -c .test "$B")" '{"exit":0,"passed":10,"skipped":1}'
+
+  mover --src "$R/pkg/big.py" --plan "$P" --dry-run
+  eq "dry-run rc" "$RC" 0
+  eq "dry-run touches nothing" "$(git -C "$R" status --porcelain)" ""
+
+  mover --src "$R/pkg/big.py" --plan "$P"
+  eq "move rc" "$RC" 0
+  eq "move status" "$(q '.status')" '"ok"'
+  eq "move package" "$(q '.package')" '"pkg.big_parts"'
+  eq "move modules" "$(q '.modules|keys')" '["aio","consts","helpers","models"]'
+  eq "move module sizes" "$(q '[.modules[]|length]')" '[30,91,181,30]'
+  for f in __init__ consts helpers aio models; do
+    eq "package file $f" "$([ -f "$R/pkg/big_parts/$f.py" ] && echo yes || echo no)" yes
+  done
+  eq "package __init__ empty" "$(wc -c < "$R/pkg/big_parts/__init__.py" | tr -d ' ')" 0
+  g add -A && g commit -qm move
+  eq "shim: added lines are imports only" \
+    "$(git -C "$R" diff base HEAD -- pkg/big.py | grep '^+' | grep -v '^+++' | sed 's/^+//' \
+       | grep -vE '^\s*$|^\s*(from \S+ import|import \S)|^\s+[A-Za-z_][A-Za-z_0-9]*,$|^\)$' | wc -l | tr -d ' ')" 0
+  eq "shim keeps unmoved code" "$(grep -c '^def describe\|^VERSION = \|^DEFAULT_TOTAL = ' "$R/pkg/big.py")" 3
+  eq "symbol moved verbatim" "$(git -C "$R" show base:pkg/big.py | sed -n '/^@functools.total_ordering$/,/^class Item_00:/p' | head -2 | tr '\n' '|')" \
+    "$(sed -n '/^@functools.total_ordering$/,/^class Item_00:/p' "$R/pkg/big_parts/models.py" | head -2 | tr '\n' '|')"
+  run bash "$RV" verify --baseline "$B" --base base
+  eq "verify rc" "$RC" 0
+  eq "verify ok" "$(q '.ok')" true
+  eq "verify failures" "$(q '.failures')" '[]'
+  (cd "$R" && $TEST_CMD >"$TMP/after.txt" 2>&1); eq "tests after move" "$?" 0
+  eq "identical test result" "$(tail -1 "$TMP/after.txt")" "OK (skipped=1)"
+
+  # ---- 5. --extend (forge#4211 chain step): a second PR adds modules to the package the first one created ----
+  R2="$TMP/repo2"; B2="$TMP/baseline2.json"
+  g2() { git -C "$R2" -c user.name=t -c user.email=t@example.invalid "$@"; }
+  mkdir -p "$R2"; git init -q "$R2"; printf '__pycache__/\n' > "$R2/.gitignore"
+  python3 "$GEN" "$R2" && g2 add -A && g2 commit -qm base
+  plan '{"consts":['"$(printf '"LIMIT_%02d",' $(seq 0 89))"'"_SEPARATOR"]}' "$TMP/step1.json"
+  mover --src "$R2/pkg/big.py" --plan "$TMP/step1.json"
+  eq "chain step 1 rc" "$RC" 0
+  g2 add -A && g2 commit -qm step1 && g2 tag step1
+  plan '{"helpers":['"$(for i in $(seq -w 0 89); do printf '"_scale_%s","compute_%s",' "$i" "$i"; done)"'"join_parts"]}' "$TMP/step2.json"
+  mover --src "$R2/pkg/big.py" --plan "$TMP/step2.json"
+  eq "existing package without --extend: rc" "$RC" 3
+  eq "existing package without --extend: reason" "$(q '.reason|contains("already exists")')" true
+  eq "existing package without --extend: untouched" "$(git -C "$R2" status --porcelain)" ""
+  jq -c '{consts: .helpers}' "$TMP/step2.json" > "$TMP/step2bad.json"
+  mover --src "$R2/pkg/big.py" --plan "$TMP/step2bad.json" --extend
+  eq "--extend colliding module: rc" "$RC" 3
+  eq "--extend colliding module: reason" "$(q '.reason|contains("module already exists")')" true
+  eq "--extend colliding module: untouched" "$(git -C "$R2" status --porcelain)" ""
+  run bash "$RV" baseline --root "$R2" --target pkg/big.py --test-cmd "$TEST_CMD" --out "$B2"
+  eq "chain baseline rc" "$RC" 0
+  INIT_SHA="$(git -C "$R2" hash-object pkg/big_parts/__init__.py)"
+  mover --src "$R2/pkg/big.py" --plan "$TMP/step2.json" --extend
+  eq "--extend rc" "$RC" 0
+  eq "--extend package" "$(q '.package')" '"pkg.big_parts"'
+  eq "--extend modules" "$(q '.modules|keys')" '["helpers"]'
+  eq "--extend keeps __init__" "$(git -C "$R2" hash-object pkg/big_parts/__init__.py)" "$INIT_SHA"
+  eq "--extend keeps step-1 module" "$(git -C "$R2" status --porcelain pkg/big_parts/consts.py)" ""
+  g2 add -A && g2 commit -qm step2
+  run bash "$RV" verify --baseline "$B2" --base step1
+  eq "--extend verify rc" "$RC" 0
+  eq "--extend verify failures" "$(q '.failures')" '[]'
+fi
+
+echo "symbol-move.test.sh: $PASS passed, $FAILN failed"
+[ "$FAILN" -eq 0 ]

package/templates/bootstrap/interview.md

@@ -0,0 +1,34 @@
+<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+# /bootstrap interview question bank
+
+Ask conversationally and keep it short: skip any aspect the user's free text or docs already answer. Every aspect left
+unanswered gets the **Default** and its rationale, tied to what the user did say, in the "Here's what I assumed" summary.
+Aspects marked **Doubt** change architecture or cost. When the answer is unclear, ask them as multiple-choice questions
+(at most 4 per batch, each with a recommended option). All other aspects default silently.
+
+| # | Aspect | Question | Default (rationale pattern) | Doubt? |
+|---|--------|----------|-----------------------------|--------|
+| 1 | Users and segments | Who uses it, and which segments differ in what they need? | One primary segment from the pitch; admins as a second role (most products need an operator view) | no |
+| 2 | Core jobs and features | What must a user be able to do on day one? | The jobs named in the pitch, each as a feature with its happy path | no |
+| 3 | Scope | MVP first, or the full product? | MVP, full product as later milestones (cheapest path to feedback) | yes, when the pitch lists many features |
+| 4 | Platforms | Web, mobile, desktop? | Responsive web (one codebase covers phones) | yes: mobile native vs PWA |
+| 5 | Stack | Any language, framework or hosting preferences? | The closest preset in `stack-profiles.md` | no, unless the user names conflicting stacks |
+| 6 | Auth | How do users sign in? | Email magic link + Google sign-in (lowest friction, no password storage) | no |
+| 7 | Data and tenancy | Is data shared between organisations? | Postgres + row-level security for multi-tenant SaaS; single-tenant otherwise | yes: self-host vs managed DB |
+| 8 | Integrations | Which external services? | A mock provider per credentialed integration so dev and CI stay green | no |
+| 9 | Payments | Do you charge, and how? | Stripe subscriptions behind a mock in dev (most common, test mode is free) | yes, when pricing is unclear |
+| 10 | i18n | Which languages and locales? | English with i18n-ready strings (cheap now, expensive later) | no |
+| 11 | Compliance and residency | Any regulation (GDPR, HIPAA, DPDP) or data-residency rule? | Privacy by default (minimal PII, encrypted at rest); region of the primary market | yes: data residency |
+| 12 | Design ambition and UI libraries | Polished brand or functional? Any UI library? | Accessible component library (e.g. shadcn/ui) plus a design-token theme; hero surfaces go to `/design` | no |
+| 13 | Deployment target | VPS, Cloudflare or a cloud provider? | The stack preset's target with a staging-branch flow (staging -> main) | yes: when the cost profile differs |
+| 14 | Scale | Users and data in year one? | Small (hundreds of users): one region, one DB, a scale path in the spike | no |
+| 15 | Budget | Monthly infra budget? | Free or hobby tiers until launch | no |
+| 16 | Team | Who builds and reviews? | A solo builder with ForgeDock agents | no |
+| 17 | Timeline | Any hard date? | None: milestones in build order | no |
+
+Always a doubt: the **product name** and the **repo owner** (user or org; the owner must be covered by the ForgeDock
+GitHub App installation).
+
+Guardrails and domain rules (e.g. "no auto-send", "India-only data residency") go into the plan's `guardrails` and
+`domainRules`. bootstrap-create.mjs copies them into every issue's Context.

package/templates/bootstrap/issue-body.md

@@ -0,0 +1,42 @@
+<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+<!-- /bootstrap build-issue body (Pipeline Issue Template). Copy from "## Problem" down; drop the UI block for
+non-UI issues and the hero line for non-hero issues. Plan flags: "ui": true needs the full design spec, "hero": true
+needs the /design line (scripts/bootstrap-validate.mjs). Reference other plan issues as #{{KEY}}. -->
+## Problem
+
+{what this issue delivers and for whom, one paragraph}
+
+## Root Cause (if known)
+
+Greenfield: not built yet. {spike section this implements}
+
+## Affected Files
+
+1. `{planned/path/file.ext}` — new
+2. `{planned/path/other.ext}` — new
+
+## Acceptance Criteria
+
+- [ ] {observable behaviour} [type:unit]
+- [ ] {API or integration behaviour} [type:api]
+- [ ] {user-visible flow} [type:e2e]
+
+### Design spec (UI issues)
+
+- **Breakpoints**: {mobile 360, tablet 768, desktop 1280: layout at each}
+- **States**: empty state {copy and action}; loading state {skeleton}; error state {message and retry}; offline state {cached view or banner}
+- **Motion**: {transitions and durations; respects prefers-reduced-motion}
+- **Accessibility**: {WCAG 2.2 AA: focus order, labels, contrast, keyboard paths}
+- **Dark mode**: {token mapping; verified in both themes}
+- **Hero surface**: route the visual design to `/design` before building this page.
+
+## Context
+
+**Parent**: #{{SPIKE}}
+Spike: `docs/engineering/technical-spike.md` § {section}
+{real credentials: see #{{NEEDS_HUMAN_KEY}}; until then the mock provider is used, so this issue never depends on it}
+
+## Dependencies
+
+Depends on #{{DEP_KEY}} — {why}