@techierathore/techieflow 1.0.2 → 1.0.3

package/.tfcore/utils/tf-day1-files.py

@@ -0,0 +1,208 @@
+#!/usr/bin/env python3
+"""tf-day1-files.py — the mechanical part of day-1 (see tf-day1-files.sh).
+
+    bash .tfcore/utils/tf-day1-files.sh <App> [--size S|M|L] [--kind app|library] [--prefix obj|none] [--phase N]
+    bash .tfcore/utils/tf-day1-files.sh --archive <file> [<file> ...]
+
+Default mode, for <App>:
+  - .tfcore/core-config.yaml: customTechnicalDocuments (brd, architecture, codingStandards),
+    devLoadAlwaysFiles, and appSize / appKind / appPhase when given.
+  - --size L also writes docs/<App>-Phases.md from app-phases-tmpl.md when it does not exist
+    (the Large layout: docs/TechieFlow-Document-Schemas.md §2, §3.11). The agent fills the table.
+  - --phase N sets appPhase, the phase being worked (handoff moves it on).
+  - .editorconfig from app-editorconfig-tmpl.editorconfig (overwritten; machine config).
+  - AGENTS.md and CLAUDE.md from their templates with {AppName} substituted and the
+    field-prefix line resolved (--prefix, default obj). An existing copy is archived first.
+--archive: move each file (and its sibling .html) to docs/OldDocs/, date-suffixed when a
+file of that name is already there. Never asks; never writes a -v2 variant.
+
+Prints one line per thing done. Python 3 standard library only. Exit 0 done, 2 could not run.
+"""
+import datetime
+import os
+import re
+import shutil
+import sys
+
+TPL = os.path.join(".tfcore", "templates", "v4custom")
+PREFIX_TEXT = {
+    "obj": "`obj` prefix on instance fields (e.g. `private readonly ILogger<X> objLogger;`)",
+    "none": "bare PascalCase, no prefix",
+}
+
+
+def die(msg):
+    print(f"tf-day1-files: {msg}", file=sys.stderr)
+    sys.exit(2)
+
+
+def read(p):
+    with open(p, encoding="utf-8", errors="replace") as f:
+        return f.read()
+
+
+def write(p, s):
+    with open(p, "w", encoding="utf-8", newline="\n") as f:
+        f.write(s)
+
+
+def archive(path):
+    """Move path (and its sibling .html) to docs/OldDocs/, date-suffixed on collision."""
+    if not os.path.isfile(path):
+        return
+    old = os.path.join("docs", "OldDocs")
+    os.makedirs(old, exist_ok=True)
+    for p in (path, os.path.splitext(path)[0] + ".html"):
+        if not os.path.isfile(p):
+            continue
+        dest = os.path.join(old, os.path.basename(p))
+        if os.path.exists(dest):
+            stem, ext = os.path.splitext(os.path.basename(p))
+            dest = os.path.join(old, f"{stem}-{datetime.date.today().strftime('%Y%m%d')}{ext}")
+            n = 1
+            while os.path.exists(dest):
+                n += 1
+                dest = os.path.join(old, f"{stem}-{datetime.date.today().strftime('%Y%m%d')}-{n}{ext}")
+        shutil.move(p, dest)
+        print(f"tf-day1-files: archived {p} -> {dest}")
+
+
+def set_key(text, key, value_lines):
+    """Replace a top-level YAML key (scalar or block) with the given lines; append if absent."""
+    lines = text.splitlines()
+    out, i, done = [], 0, False
+    while i < len(lines):
+        if re.match(rf"^{re.escape(key)}:", lines[i]):
+            out.extend(value_lines)
+            i += 1
+            while i < len(lines) and (lines[i].startswith((" ", "\t")) or lines[i].strip() == "" and i + 1 < len(lines) and lines[i + 1].startswith(" ")):
+                i += 1
+            done = True
+            continue
+        out.append(lines[i])
+        i += 1
+    if not done:
+        out.extend(value_lines)
+    return "\n".join(out) + "\n"
+
+
+def update_config(app, size, kind, phase):
+    p = os.path.join(".tfcore", "core-config.yaml")
+    if not os.path.isfile(p):
+        die(f"{p} does not exist at its literal path; is the framework installed here?")
+    s = read(p)
+    s = set_key(s, "customTechnicalDocuments", [
+        "customTechnicalDocuments:",
+        f"  brd: docs/{app}-BRD.md",
+        f"  architecture: docs/{app}-Architecture.md",
+        f"  codingStandards: docs/{app}-Coding-Standards.md",
+    ])
+    s = set_key(s, "devLoadAlwaysFiles", [
+        "devLoadAlwaysFiles:",
+        f"  - docs/{app}-Coding-Standards.md",
+        f"  - docs/{app}-Architecture.md",
+    ])
+    if size:
+        s = set_key(s, "appSize", [f"appSize: {size}"])
+    if kind:
+        s = set_key(s, "appKind", [f"appKind: {kind}"])
+    if phase:
+        s = set_key(s, "appPhase", [f"appPhase: {phase}"])
+    write(p, s)
+    print(f"tf-day1-files: .tfcore/core-config.yaml updated (documents for {app}"
+          + (f", appSize {size}" if size else "") + (f", appKind {kind}" if kind else "")
+          + (f", appPhase {phase}" if phase else "") + ")")
+
+
+def write_phases_doc(app):
+    """docs/<App>-Phases.md from its template, only when absent (Large projects)."""
+    dest = os.path.join("docs", f"{app}-Phases.md")
+    if os.path.isfile(dest):
+        print(f"tf-day1-files: {dest} already exists; left as is")
+        return
+    src = os.path.join(TPL, "app-phases-tmpl.md")
+    if not os.path.isfile(src):
+        die(f"template {src} does not exist at its literal path")
+    os.makedirs("docs", exist_ok=True)
+    body = read(src).replace("{App}", app).replace("{YYYY-MM-DD}", datetime.date.today().isoformat())
+    write(dest, body)
+    print(f"tf-day1-files: wrote {dest} skeleton; fill the Phases table (one row per phase, each within Medium)")
+
+
+def write_from_template(app, tmpl, dest, prefix):
+    src = os.path.join(TPL, tmpl)
+    if not os.path.isfile(src):
+        die(f"template {src} does not exist at its literal path")
+    body = read(src).replace("{AppName}", app)
+    if prefix:
+        body = re.sub(r"\{obj prefix on instance fields[^}]*\| bare PascalCase, no prefix\}", PREFIX_TEXT[prefix], body)
+    if os.path.isfile(dest) and read(dest) == body:
+        print(f"tf-day1-files: {dest} already current")
+        return
+    if dest != ".editorconfig":
+        archive(dest)
+    write(dest, body)
+    print(f"tf-day1-files: wrote {dest}")
+
+
+def main(argv):
+    if len(argv) < 2 or argv[1] in ("-h", "--help"):
+        print(__doc__)
+        return 0
+    if argv[1] == "--archive":
+        if len(argv) < 3:
+            die("--archive needs at least one file")
+        for f in argv[2:]:
+            if os.path.isfile(f):
+                archive(f)
+            else:
+                print(f"tf-day1-files: {f} does not exist; nothing to archive")
+        return 0
+    app = argv[1]
+    if not re.fullmatch(r"[A-Z][A-Za-z0-9]*", app):
+        die(f"app name {app!r} must be PascalCase with no spaces")
+    size = kind = phase = None
+    prefix = "obj"
+    args = argv[2:]
+    i = 0
+    while i < len(args):
+        a = args[i]
+        if a == "--size" and i + 1 < len(args):
+            v = args[i + 1].strip().upper()[:1]
+            if v not in ("S", "M", "L"):
+                die("--size must be S, M or L")
+            size = v
+            i += 2
+        elif a == "--phase" and i + 1 < len(args):
+            if not args[i + 1].isdigit() or int(args[i + 1]) < 1:
+                die("--phase must be a number from 1 upwards")
+            phase = int(args[i + 1])
+            i += 2
+        elif a == "--kind" and i + 1 < len(args):
+            kind = args[i + 1].strip().lower()
+            if kind not in ("app", "library"):
+                die("--kind must be app or library")
+            i += 2
+        elif a == "--prefix" and i + 1 < len(args):
+            prefix = args[i + 1].strip().lower()
+            if prefix not in PREFIX_TEXT:
+                die("--prefix must be obj or none")
+            i += 2
+        else:
+            die(f"unknown argument {a!r}")
+    update_config(app, size, kind, phase)
+    if size == "L":
+        write_phases_doc(app)
+    write_from_template(app, "app-editorconfig-tmpl.editorconfig", ".editorconfig", None)
+    write_from_template(app, "app-agents-md-tmpl.md", "AGENTS.md", prefix)
+    write_from_template(app, "app-claude-md-tmpl.md", "CLAUDE.md", prefix)
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(main(sys.argv))
+    except SystemExit:
+        raise
+    except Exception as e:
+        die(str(e))

package/.tfcore/utils/tf-day1-files.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# tf-day1-files.sh — the mechanical part of day-1.
+#
+#   bash .tfcore/utils/tf-day1-files.sh MyApp --size S --kind app          # config entries (stage 1)
+#   bash .tfcore/utils/tf-day1-files.sh MyApp --prefix obj                 # .editorconfig, AGENTS.md, CLAUDE.md (stage 2)
+#   bash .tfcore/utils/tf-day1-files.sh --archive docs/MyApp-BRD.md ...    # move old copies to docs/OldDocs/
+#   bash .tfcore/utils/tf-day1-files.sh MyApp --phase 2                    # Large project: the phase being worked
+#
+# Writes core-config.yaml keys (customTechnicalDocuments, devLoadAlwaysFiles,
+# appSize, appKind, appPhase), writes docs/MyApp-Phases.md from its template on
+# --size L when absent, and copies the three scaffold files from their templates
+# with {AppName} substituted. Archives an existing AGENTS.md / CLAUDE.md first.
+# Never asks a question. Thin wrapper over tf-day1-files.py; Python 3 stdlib only.
+set -uo pipefail
+SELF_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+if ! command -v python3 >/dev/null 2>&1; then
+  echo "tf-day1-files: python3 is required (standard library only)." >&2
+  exit 2
+fi
+exec python3 "$SELF_DIR/tf-day1-files.py" "$@"

package/.tfcore/utils/tf-devguide-list.py

@@ -0,0 +1,249 @@
+#!/usr/bin/env python3
+"""tf-devguide-list.py — the work list for *devguide (see tf-devguide-list.sh).
+
+    bash .tfcore/utils/tf-devguide-list.sh <App> [--phase N] [--update]
+
+Reads appKind and appPhase from .tfcore/core-config.yaml and prints:
+  app             every routed page found in the code (route, file), matched to the phase's
+                  UIDesign screens and to the roles in the UsageGuide's Test users table;
+                  UIDesign screens with no code (a defect), routes with no UIDesign screen
+  ui library      every public component under src/ (not the samples), with the sample page
+                  that shows it, or "no sample" (a gap)
+  service library every public service: DI registration methods, public interfaces and
+                  classes under src/, with the sample that calls it, or "no sample"
+  --update        which existing guide entries have files newer than the guide's "Verified on"
+Prints NOTHING when no code is found. Writes nothing. Python 3 standard library only.
+"""
+import os
+import re
+import sys
+
+SKIP = ("/bin/", "/obj/", "/node_modules/", "/.artifacts/", "/OldDocs/", "/.git/", "/dist/", "/wwwroot/lib/")
+SAMPLE_DIRS = ("samples", "sample", "demos", "demo", "apps", "examples", "tests")
+ROUTE_PATTERNS = [   # (file pattern, route pattern, page or endpoint)
+    (r"\.(razor|cshtml)$", re.compile(r'(?m)^\s*@page\s+"([^"]+)"'), "page"),
+    (r"\.cs$", re.compile(r'\[(?:Http(?:Get|Post|Put|Delete)|Route)\(\s*"([^"]+)"'), "endpoint"),
+    (r"\.(ts|tsx|js|jsx|vue)$", re.compile(r'''\bpath\s*:\s*['"]([^'"]+)['"]'''), "page"),
+    (r"\.(tsx|jsx)$", re.compile(r'''<Route\b[^>]*\bpath\s*=\s*['"]([^'"]+)['"]'''), "page"),
+]
+
+
+def die(msg):
+    print(f"tf-devguide-list: {msg}", file=sys.stderr)
+    sys.exit(2)
+
+
+def read(p):
+    with open(p, encoding="utf-8-sig", errors="replace") as f:   # -sig: a byte-order mark never hides line 1
+        return f.read()
+
+
+def cfg(key, default):
+    p = os.path.join(".tfcore", "core-config.yaml")
+    if os.path.isfile(p):
+        m = re.search(rf"(?m)^{key}:\s*(\S+)", read(p))
+        if m and m.group(1) not in ("null", "~"):
+            return m.group(1).strip("'\"")
+    return default
+
+
+PRUNE = {"bin", "obj", "node_modules", ".git", ".artifacts", "OldDocs", "dist", ".tfcore", ".claude", ".opencode", "packages", "TestResults"}
+
+
+def walk(root, exts, skip_samples=False):
+    for d, dirs, files in os.walk(root):
+        dirs[:] = [x for x in dirs if x not in PRUNE]   # prune in place: never descend into build output
+        dd = d.replace("\\", "/") + "/"
+        if any(s in dd for s in SKIP):
+            continue
+        if skip_samples and any(f"/{s}/" in dd or dd.endswith(f"/{s}/") for s in SAMPLE_DIRS):
+            continue
+        for f in files:
+            if f.lower().endswith(exts):
+                yield os.path.join(d, f).replace("\\", "/").lstrip("./")
+
+
+def roles_from_usageguide(app):
+    p = os.path.join("docs", f"{app}-UsageGuide.md")
+    roles = []
+    if os.path.isfile(p):
+        m = re.search(r"(?ms)^##\s+(?:\d+[.)]\s*)?Test users[^\n]*\n(.*?)(?=^## |\Z)", read(p))
+        if m:
+            for line in m.group(1).splitlines():
+                c = [x.strip() for x in line.strip().strip("|").split("|")]
+                if len(c) >= 4 and c[0].strip("`* ").isdigit():
+                    roles.append((c[1].strip("`* "), c[3].strip("`* ")))
+    return roles
+
+
+def screens_from_uidesign(app, phase):
+    pfx = f"{app}-" if phase <= 1 else f"{app}-P{phase}-"
+    p = os.path.join("docs", f"{pfx}UIDesign.md")
+    out = []
+    if os.path.isfile(p):
+        for m in re.finditer(r"(?m)^###\s+Screen:\s*(.+?)\s*\(`?([^)`]+)`?\)\s*$", read(p)):
+            out.append((m.group(1).strip(), m.group(2).strip()))
+    return out, p
+
+
+def routes_in_code():
+    found = []
+    for f in walk(".", (".razor", ".cshtml", ".cs", ".ts", ".tsx", ".js", ".jsx", ".vue")):
+        if "/" not in f:
+            continue   # a top-level file is never a page
+        txt = read(f)
+        for ext_re, pat, what in ROUTE_PATTERNS:
+            if re.search(ext_re, f, re.I):
+                for m in pat.finditer(txt):
+                    r = m.group(1).strip()
+                    if r and not r.startswith("http") and "[" not in r:   # "[controller]/[action]" is a template, not a page
+                        found.append((r, f, what))
+    return found
+
+
+def norm_route(r):
+    """'/ManageAccount/{PageId:int}' -> '/manageaccount' : parameters and case never decide a match."""
+    r = r.strip().rstrip("/").lower()
+    r = re.sub(r"/\{[^}]+\}|/:[a-z_]+", "", r)
+    return r or "/"
+
+
+def sample_files(exts):
+    """Files under the sample folders only (samples/, demos/, apps/, examples/), never the whole tree."""
+    out = []
+    for d in SAMPLE_DIRS:
+        if d == "tests":
+            continue
+        if os.path.isdir(d):
+            out += list(walk(d, exts))
+    return out
+
+
+def existing_entries(app, phase):
+    pfx = f"{app}-" if phase <= 1 else f"{app}-P{phase}-"
+    p = os.path.join("docs", f"{pfx}DevGuide.md")
+    if not os.path.isfile(p):
+        return p, None, []
+    txt = read(p)
+    m = re.search(r"(?im)^\|\s*Verified on\s*\|\s*([^|]+?)\s*\|", txt)
+    return p, (m.group(1).strip() if m else None), re.findall(r"(?m)^###\s+(.+)$", txt)
+
+
+def main(argv):
+    if len(argv) < 2 or argv[1] in ("-h", "--help"):
+        print(__doc__)
+        return 0
+    app = argv[1]
+    update = "--update" in argv
+    phase = int(argv[argv.index("--phase") + 1]) if "--phase" in argv and argv.index("--phase") + 1 < len(argv) else int(cfg("appPhase", "1"))
+    kind = cfg("appKind", "app").lower()
+    if "--kind" in argv and argv.index("--kind") + 1 < len(argv):
+        kind = argv[argv.index("--kind") + 1].lower()   # override for a project whose config lacks it
+    sub = "app"
+    if kind.startswith("lib"):
+        razors = [f for f in walk("src", (".razor",), skip_samples=True)] if os.path.isdir("src") else []
+        sub = "ui-library" if razors else "service-library"
+    print(f"# tf-devguide-list — {app} — kind {sub} — phase {phase}")
+    print()
+
+    if sub == "app":
+        screens, uip = screens_from_uidesign(app, phase)
+        routes = routes_in_code()
+        if not routes:
+            print("NOTHING: no routed page found in the code (no @page, [Route], or path: declaration outside samples and tests). Build first.")
+            return 0
+        roles = roles_from_usageguide(app)
+        by_route, endpoints = {}, {}
+        for r, f, what in routes:
+            if what == "endpoint":
+                endpoints.setdefault(norm_route(r), []).append(f)
+            else:
+                by_route.setdefault(norm_route(r), []).append(f)
+        if not by_route:
+            print("NOTHING: no routed page found in the code; only API endpoints. Build the screens first.")
+            return 0
+        print(f"## Work list — {len(by_route)} route(s) in code, {len(screens)} screen(s) in {os.path.basename(uip)}, roles: " + (", ".join(sorted({r for _u, r in roles})) or "none in the UsageGuide"))
+        matched = set()
+        for name, route in screens:
+            key = norm_route(route)
+            files = by_route.get(key)
+            if files:
+                matched.add(key)
+                print(f"- {name} ({route}) — {', '.join(sorted(set(files))[:3])}")
+            else:
+                print(f"- {name} ({route}) — NO CODE FOUND for this route: log it as a defect on the screen's row")
+        extra = [k for k in by_route if k not in matched]
+        if extra:
+            print()
+            print("## Pages in code with no UIDesign screen (document them, and tell the analyst)")
+            for k in sorted(extra):
+                print(f"- {k} — {', '.join(sorted(set(by_route[k]))[:3])}")
+        if endpoints:
+            print()
+            print(f"## API endpoints ({len(endpoints)}; not screens, the call chains end here)")
+            for k in sorted(endpoints):
+                print(f"- {k} — {', '.join(sorted(set(endpoints[k]))[:2])}")
+    elif sub == "ui-library":
+        comps = [f for f in walk("src", (".razor",), skip_samples=True)]
+        if not comps:
+            print("NOTHING: no component under src/. Build first.")
+            return 0
+        samples = sample_files((".razor", ".cshtml", ".html"))
+        stxt = {f: read(f) for f in samples}
+        print(f"## Work list — {len(comps)} component(s), grouped by folder; {len(samples)} sample page(s)")
+        for f in sorted(comps):
+            name = os.path.splitext(os.path.basename(f))[0]
+            shown = [s for s, t in stxt.items() if re.search(rf"<{re.escape(name)}\b", t)]
+            print(f"- {os.path.dirname(f).split('/')[-1]} / {name} — {f} — " + (f"shown in {shown[0]}" + (f" (+{len(shown)-1})" if len(shown) > 1 else "") if shown else "NO SAMPLE shows it: a sample gap to log"))
+    else:
+        files = [f for f in walk("src", (".cs", ".ts", ".py", ".go", ".java"), skip_samples=True)]
+        if not files:
+            print("NOTHING: no source under src/. Build first.")
+            return 0
+        items = []
+        for f in files:
+            t = read(f)
+            for m in re.finditer(r"public\s+static\s+\w[\w<>,\s]*\s+(Add\w+)\s*\(\s*this\s+", t):
+                items.append(("registration", m.group(1), f))
+            for m in re.finditer(r"public\s+(?:partial\s+)?interface\s+(I\w+)", t):
+                items.append(("interface", m.group(1), f))
+            for m in re.finditer(r"public\s+(?:sealed\s+|abstract\s+)?(?:partial\s+)?class\s+(\w+)", t):
+                items.append(("class", m.group(1), f))
+        samples = sample_files((".cs", ".razor", ".ts", ".py"))
+        stxt = {f: read(f) for f in samples}
+        items = sorted(set(items), key=lambda x: (x[0] != "registration", x[0] != "interface", x[1]))   # overloads once
+        print(f"## Work list — {len(items)} public item(s) under src/, {len(samples)} sample file(s)")
+        for kind_, name, f in items:
+            used = [s for s, t in stxt.items() if re.search(rf"\b{re.escape(name)}\b", t)]
+            print(f"- {kind_} {name} — {f} — " + (f"called in {used[0]}" + (f" (+{len(used)-1})" if len(used) > 1 else "") if used else "NO SAMPLE calls it: a sample gap to log"))
+
+    if update:
+        gp, ver, entries = existing_entries(app, phase)
+        print()
+        if ver is None:
+            print(f"## --update: no existing guide at {gp} (or no \"Verified on\"); everything is new")
+        else:
+            print(f"## --update: existing guide {gp}, Verified on {ver}, {len(entries)} entries")
+            try:
+                import datetime
+                cutoff = datetime.datetime.strptime(ver[:10], "%Y-%m-%d").timestamp()
+            except Exception:
+                cutoff = None
+            if cutoff:
+                changed = [f for f in walk(".", (".razor", ".cshtml", ".cs", ".ts", ".tsx", ".js", ".py"), skip_samples=False)
+                           if f.startswith(("src/",)) and os.path.getmtime(f) > cutoff]
+                print(f"- {len(changed)} source file(s) changed since then; remap the entries they serve, keep the rest verbatim")
+                for f in changed[:30]:
+                    print(f"  - {f}")
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(main(sys.argv))
+    except SystemExit:
+        raise
+    except BrokenPipeError:
+        sys.exit(0)   # piped into head: not an error
+    except Exception as e:
+        die(str(e))

package/.tfcore/utils/tf-devguide-list.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+# tf-devguide-list.sh — the work list for *devguide.
+#
+#   bash .tfcore/utils/tf-devguide-list.sh MyApp              # app: routes in code vs UIDesign screens, roles
+#   bash .tfcore/utils/tf-devguide-list.sh MyApp --update     # plus which existing entries changed
+#   bash .tfcore/utils/tf-devguide-list.sh MyApp --phase 2    # a later phase of a Large project
+#
+# Kind comes from core-config.yaml: an app lists routed pages; a UI library its public
+# components and the sample page that shows each; a service library its registrations,
+# interfaces and classes and the sample that calls each. Prints NOTHING when no code exists.
+# Writes nothing. Thin wrapper over tf-devguide-list.py; Python 3 stdlib only.
+set -uo pipefail
+SELF_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+if ! command -v python3 >/dev/null 2>&1; then
+  echo "tf-devguide-list: python3 is required (standard library only)." >&2
+  exit 2
+fi
+exec python3 "$SELF_DIR/tf-devguide-list.py" "$@"