@passioncode-ai/fabric-agent-adapter 0.82.0 → 0.83.1

package/plugins/fabric-agent-adapter/skills/adapting-projects-to-fabric/scripts/fabric_source_check.py

@@ -38,7 +38,7 @@ unset the walk is used). A committed symbolic link is checked by the path it nam
 its first 8 KiB) is not read; it is listed. Globs in ROOT's `.fabric-source-ignore` (one per line, `#`
 comments) and `--exclude` leave matching paths out. The owner's list is `--instance-strings`, else the file
 `FABRIC_INSTANCE_STRINGS` names, else `passioncode-fabric/instance-strings.txt` in the user's configuration folder
-(`$XDG_CONFIG_HOME` when it is absolute, else `~/.config`; `%APPDATA%` on Windows) when it exists: one string per
+(`$XDG_CONFIG_HOME` when it is absolute, else `~/.config`; `%APPDATA%` when absolute on Windows) when it exists: one string per
 line, a line starting with `#` a comment, `home: <name>` declaring the owner's home name (never neutral), strings
 shorter than three characters ignored, matched without regard to case. A list inside ROOT
 is refused: it would travel with the source. The summary says whether Git chose the files or every file was read.
@@ -95,6 +95,9 @@ def _refuse_sibling(step: str, missing: BaseException) -> NoReturn:
 
 _WROTE_BYTECODE, sys.dont_write_bytecode = sys.dont_write_bytecode, True  # a copy inside the checked tree adds no .pyc
 _STEP = "fabric_secrets"  # the sibling being loaded, so a refusal names it whatever the exception says
+#: The public names of fabric_secrets the check and its command line read (FAA-190 (2), (12)), checked when it loads.
+SECRETS_NAMES = ("BEARER_INSIDE", "JS_SPACE", "NOT_LINE_END", "SCHEME", "credential_name", "has_jwt", "jwt_spans",
+                 "long_secret", "raw_values", "secret_value", "url_parts")
 try:
     import fabric_secrets as _secrets  # noqa: E402 - the contract's credential detector (DEC-0044), beside this file
     _STEP = "fabric_source_ignore"
@@ -105,12 +108,18 @@ try:
     _STEP = "fabric_source_homes"
     from fabric_source_homes import (  # noqa: E402,F401 - how a declared home is read, beside this file
         HOME_ENTRY, _NAME_JOIN, _NAME_START, _SEP, _dashed_home, _name_parts, _owner_homes, _spellings)
+    _STEP = "fabric_source_check_cli"
+    from fabric_source_check_cli import (  # noqa: E402,F401 - the command line, beside this file (FAA-190 (104))
+        LIST_NAME, _Parser, _absolute, _list_path, _print, default_list, run_check)
+    _STEP = "fabric_secrets"
+    for _name in SECRETS_NAMES:  # a detector from another version fails here, never at the first file read (FAA-190 (89))
+        if not hasattr(_secrets, _name):
+            raise ImportError(_name)
 except Exception as _missing:  # a copy without its siblings, or mixed from two versions: a refusal, never exit 1
     _refuse_sibling(_STEP, _missing)
 finally:
     sys.dont_write_bytecode = _WROTE_BYTECODE
 
-LIST_NAME = "instance-strings.txt"
 #: The folders `pack` refuses to carry (fabric_package.JUNK); --every-file leaves them and the files below unread.
 PACK_REFUSES = {".git", "__pycache__"}
 WALK_SKIP = {".git", "node_modules", "__pycache__", ".venv", "venv", ".tox", ".mypy_cache", ".pytest_cache"}
@@ -145,12 +154,12 @@ SYNTHETIC = ("example", "not-a-key", "notakey", "fake", "dummy", "placeholder",
 # This check's own key shapes, the detector's before DEC-0151 (unbounded, ASCII case-insensitive), apart from the shared
 # SECRET_VALUE for parity with the contract's tree check (KEY_SHAPE_SOURCES, `src/source-rules.ts` at the pin; CT-207,
 # FAA-258). Not the detector's `^bearer\s.+`, which reads a whole header value and would take prose that starts with the
-# word: a bearer token is looked for as `_BEARER_INSIDE` does, the word, then a run of 12 or more with a digit.
+# word: a bearer token is looked for as `BEARER_INSIDE` does, the word, then a run of 12 or more with a digit.
 KEY_SHAPE_SOURCES = ("sk-[A-Za-z0-9_-]{16,}", "gh[pousr]_[A-Za-z0-9]{20,}", "xox[abposr]-[A-Za-z0-9-]{10,}", "AKIA[0-9A-Z]{16}", "glpat-[A-Za-z0-9_-]{20,}")
 PROVIDER_KEY = re.compile("(" + "|".join(KEY_SHAPE_SOURCES) + ")", re.IGNORECASE | re.ASCII)
 #: A URL parameter's value read as the contract's tree check reads it (`URL_SECRET_VALUE` in `src/source-rules.ts`): the
 #: detector's whole-value `^bearer` branch and this check's own unbounded shapes, never the shared DEC-0151 detector.
-URL_SECRET_VALUE = re.compile("(^bearer[" + _secrets.JS_SPACE + "]" + _secrets._NOT_LINE_END + "+|" + "|".join(KEY_SHAPE_SOURCES) + ")",
+URL_SECRET_VALUE = re.compile("(^bearer[" + _secrets.JS_SPACE + "]" + _secrets.NOT_LINE_END + "+|" + "|".join(KEY_SHAPE_SOURCES) + ")",
                               re.IGNORECASE | re.ASCII)
 #: Files that are credentials by their name: pack's own rule (fabric_package.SECRET_FILE and SECRET_FILE_OK, held
 #: equal by test_source_check), and the kit's token files (`service.token`, fabric_auth; `board.credential`, fabric_hub).
@@ -217,7 +226,7 @@ def _url_secret(url: str, depth: int = 0) -> bool:
     So: a password of 8 or more mixing letters and digits, or a query or fragment value that, percent-decoded, is shaped
     like a credential (a provider key, a JWT, a long random run under a credential's name)."""
     url = url.rstrip(".,;)]}")
-    if not _secrets._SCHEME.match(url):
+    if not _secrets.SCHEME.match(url):
         return False
     password, query, fragment = _secrets.url_parts(url)
     # what says it is synthetic is the value, never the host or the path (`examples.blob.core.windows.net`)
@@ -233,7 +242,7 @@ def _url_secret(url: str, depth: int = 0) -> bool:
                     return True
                 if not _real(value):
                     continue
-                if (_secrets.credential_name(name) and _secrets._long_secret(value)) or \
+                if (_secrets.credential_name(name) and _secrets.long_secret(value)) or \
                         _secrets.has_jwt(value) or URL_SECRET_VALUE.search(value):
                     return True
     return False
@@ -293,13 +302,13 @@ def _secret_in(line: str) -> Optional[str]:
     # with a segment ending in `sk` (`task-management-service`) would read as a key.
     if any(True for _ in _provider_keys(line)):
         return "a value shaped like a provider key"
-    if any(_real(m.group(0)) for m in _overlapping(_secrets._BEARER_INSIDE, line)):
+    if any(_real(m.group(0)) for m in _overlapping(_secrets.BEARER_INSIDE, line)):
         return "a bearer token"
     if "://" in line and any(_url_secret(m.group(0)) for m in URL.finditer(line)):
         return "a URL that carries a credential"
     for m in (_assigned(line) if ":" in line or "=" in line else ()):
         name, value = m.group(1), m.group(2)
-        if _credential(name, value, _quoted(line, m)) and _secrets._long_secret(unquote(value)) and _real(unquote(value)):
+        if _credential(name, value, _quoted(line, m)) and _secrets.long_secret(unquote(value)) and _real(unquote(value)):
             return "a long random value assigned to a credential's name"
     return None
 
@@ -489,10 +498,10 @@ def _raw_secret_spans(text: str) -> List[Tuple[int, int]]:
     spans += [(a, b) for a, b in _secrets.jwt_spans(text) if _real(text[a:b])]  # one pass (FAA-313)
     spans += [m.span(1) for m in JWK_PRIVATE.finditer(text) if _real(m.group(1))]
     spans += list(_provider_keys(text))
-    spans += [m.span() for m in _overlapping(_secrets._BEARER_INSIDE, text) if _real(m.group(0))]
+    spans += [m.span() for m in _overlapping(_secrets.BEARER_INSIDE, text) if _real(m.group(0))]
     spans += [m.span() for m in URL.finditer(text) if _url_secret(m.group(0))]
     spans += [m.span(2) for m in _assigned(text)
-              if _credential(m.group(1), m.group(2), _quoted(text, m)) and _secrets._long_secret(unquote(m.group(2)))
+              if _credential(m.group(1), m.group(2), _quoted(text, m)) and _secrets.long_secret(unquote(m.group(2)))
               and _real(unquote(m.group(2)))]
     return spans
 
@@ -814,145 +823,9 @@ def check(root: Path, entries: List[str], globs: List[str], every_file: bool = F
             "dependencies": [shown(d) for d in dependencies]}
 
 
-def _absolute(path: str, platform: str) -> bool:
-    return bool(re.match(r"[A-Za-z]:[\\/]|[\\/]{2}", path)) if platform == "win32" else path.startswith("/")
-
-
-def default_list(platform: Optional[str] = None, env: Optional[Dict[str, str]] = None) -> Path:
-    """Where the owner's list is kept when none is named: the user's configuration folder, never a project's."""
-    platform = platform or sys.platform
-    env = os.environ if env is None else env
-    # a relative value is ignored, as the XDG spec says (a quoted `~/.config` is relative too): never "no list"
-    if platform == "win32":
-        appdata = env.get("APPDATA", "")
-        base = Path(appdata) if appdata and _absolute(appdata, platform) else Path.home() / "AppData" / "Roaming"
-    else:
-        xdg = env.get("XDG_CONFIG_HOME", "")
-        base = Path(xdg) if xdg.startswith("/") else Path.home() / ".config"
-    return base / "passioncode-fabric" / LIST_NAME
-
-
-def _list_path(given: Optional[str]) -> Tuple[Optional[Path], bool]:
-    """The owner's list and whether it must be read (a named or an existing default list; else no list)."""
-    named = given or os.environ.get("FABRIC_INSTANCE_STRINGS")
-    if named:
-        try:
-            return Path(named).expanduser(), True
-        except (RuntimeError, KeyError):  # `~user` with no such user (KeyError on 3.9): never "no finding"
-            raise CheckError("the owner's list cannot be read")
-    try:
-        default = default_list()
-    except (RuntimeError, KeyError):  # no HOME and no account entry (a container's arbitrary user)
-        raise CheckError("there is no home folder to find the owner's list in: set an absolute XDG_CONFIG_HOME (APPDATA on "
-                         "Windows) or name the list with --instance-strings")
-    try:
-        os.stat(str(default))
-    except (FileNotFoundError, NotADirectoryError):
-        # a link to a list, its folder or the configuration folder on a volume not mounted: there, but not reachable
-        if any(os.path.lexists(str(p)) and not os.path.exists(str(p)) for p in (default, *default.parents)):
-            raise CheckError("the owner's list in your configuration folder cannot be read")
-        return None, False
-    except OSError:  # a list that is there but cannot be reached is not "no list": that would fail open
-        raise CheckError("the owner's list cannot be read")
-    return default, True
-
-
-class _Parser(argparse.ArgumentParser):
-    def error(self, message: str) -> NoReturn:  # argparse would repeat the arguments it could not read
-        self.print_usage(sys.stderr)
-        self.exit(2, "fabric_source_check.py: the arguments cannot be read; see the usage above\n")
-
-
-def _print(text: str) -> None:
-    """Print a line the console may not encode (a name in another script, a byte Git kept as a surrogate)."""
-    encoding = getattr(sys.stdout, "encoding", None) or "utf-8"
-    print(text.encode(encoding, "backslashreplace").decode(encoding, "replace"))
-
-
 def run(argv: Optional[List[str]] = None) -> int:
-    parser = _Parser(prog="fabric_source_check.py", description="Find instance data in an agent's source.")
-    sub = parser.add_subparsers(dest="command", required=True)
-    cmd = sub.add_parser("check", help="read the source tree and report instance data without repeating it")
-    cmd.add_argument("root", nargs="?", default=".")
-    cmd.add_argument("--instance-strings", metavar="FILE")
-    cmd.add_argument("--exclude", action="append", default=[], metavar="GLOB")
-    cmd.add_argument("--json", action="store_true")
-    cmd.add_argument("--every-file", action="store_true", help="read every file, not only what Git would commit")
-    try:
-        args = parser.parse_args(argv)
-    except SystemExit as exc:  # --help, or arguments argparse refused: the exit code, as the command line gives it
-        return exc.code if isinstance(exc.code, int) else 2
-    try:
-        try:
-            root = Path(args.root).expanduser().resolve()
-            is_folder = root.is_dir()
-        except (OSError, RuntimeError, KeyError):  # a parent it cannot search, a symlink loop, `~` with no home
-            raise CheckError("the folder cannot be read")
-        if not is_folder:
-            raise CheckError("ROOT is not a folder")
-        list_path, _ = _list_path(args.instance_strings)  # may raise CheckError
-        entries: List[str] = []
-        if list_path is not None:
-            try:
-                resolved = list_path.resolve()
-            except (OSError, RuntimeError):  # RuntimeError: Python 3.9's symlink loop
-                raise CheckError("the owner's list cannot be read")
-            if resolved == root or root in resolved.parents:
-                raise CheckError("the owner's list is inside the tree it checks, where it would travel with the source; "
-                                 "keep it in your configuration folder (passioncode-fabric/%s)" % LIST_NAME)
-            try:
-                present = resolved.is_file()
-            except OSError:
-                raise CheckError("the owner's list cannot be read")
-            if not present:
-                raise CheckError("the owner's list named by --instance-strings or FABRIC_INSTANCE_STRINGS does not exist or is "
-                                 "not a regular file"
-                                 if args.instance_strings or os.environ.get("FABRIC_INSTANCE_STRINGS")
-                                 else "the owner's list in your configuration folder is not a file")
-            try:
-                entries = read_list(resolved)
-            except UnicodeDecodeError:
-                raise CheckError("the owner's list is not UTF-8")
-            except OSError:
-                raise CheckError("the owner's list cannot be read")
-        result = check(root, entries, ignore_globs(root, args.exclude), args.every_file)
-    except CheckError as exc:
-        print("fabric_source_check.py: %s" % exc, file=sys.stderr)
-        return 2
-    if result.get("manifest"):  # under fabric.source.json: its own report (fabric_source_tree.print_run)
-        return sys.modules["fabric_source_tree"].print_run(result, entries, list_path is not None, args.json, _print)
-    findings = result["findings"]
-    skipped = result["skipped"]
-    listed = sum(1 for e in entries if e and not e.startswith(HOME_ENTRY))
-    homes = sum(1 for e in entries if e.startswith(HOME_ENTRY))
-    # a binary file is not read either: it is complete only when every one is named as source in the ignore file
-    complete = not (skipped["unreadable"] or skipped["binary"] or skipped["nested"])  # type: ignore[index]
-    result.update({"instanceStrings": listed, "ownerHomes": homes, "instanceList": list_path is not None, "blocking": bool(findings),
-                   "complete": complete})
-    if args.json:
-        _print(json.dumps(result, indent=2))
-    else:
-        for f in findings:  # type: ignore[union-attr]
-            _print("%s:%s: %s (%s)" % (f["path"], f["line"], f["kind"], f["rule"]))
-        for n in result["notRead"]:  # type: ignore[union-attr]
-            _print("%s: not read (%s)" % (n["path"], n["why"]))
-        for folder in result["dependencies"]:  # type: ignore[union-attr]
-            _print("%s: not read (a dependency folder; --every-file reads it)" % folder)
-        if skipped["dependencies"]:  # type: ignore[index]
-            _print("%d dependency folder(s) not read (node_modules, virtual environments, caches); --every-file reads "
-                   "them" % skipped["dependencies"])  # type: ignore[index]
-        _print("%d file(s) read (%s), %d finding(s); not read: %d binary, %d unreadable, %d nested repository; "
-               "%d left out by name; %d instance string(s) listed%s%s"
-               % (result["files"], "what Git would commit" if result["mode"] == "git" else
-                  "every file, as pack reads them" if args.every_file else "every file but dependency folders, Git not used",
-                  len(findings), skipped["binary"], skipped["unreadable"], skipped["nested"],  # type: ignore[index]
-                  skipped["excluded"], listed,  # type: ignore[index]
-                  "" if listed or homes else (" (the owner's list holds no string of three or more characters)"
-                                              if list_path else " (no owner's list)"),
-                  "; %d home name(s) declared" % homes if homes else ""))
-    if findings:
-        return 1
-    return 0 if complete else 2
+    """The command line (fabric_source_check_cli.run_check), run with this module's check."""
+    return run_check(argv, check, read_list, ignore_globs, HOME_ENTRY)
 
 
 if __name__ == "__main__":

package/plugins/fabric-agent-adapter/skills/adapting-projects-to-fabric/scripts/fabric_source_check_cli.py

@@ -0,0 +1,164 @@
+"""The command line of fabric_source_check.py (FAA-190 (104)): where the owner's list is found, the arguments, and the
+printed report. It sits beside fabric_source_check.py, which imports it inside its import guard and keeps the entry
+point (`fabric_source_check.py check ...`, `fabric_source_check.run`); run the check by path, never this file.
+Standard library only."""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from pathlib import Path
+import re
+import sys
+from typing import Callable, Dict, List, NoReturn, Optional, Tuple
+
+from fabric_source_ignore import CheckError
+
+LIST_NAME = "instance-strings.txt"
+
+
+def _absolute(path: str, platform: str) -> bool:
+    return bool(re.match(r"[A-Za-z]:[\\/]|[\\/]{2}", path)) if platform == "win32" else path.startswith("/")
+
+
+def default_list(platform: Optional[str] = None, env: Optional[Dict[str, str]] = None) -> Path:
+    """Where the owner's list is kept when none is named: the user's configuration folder, never a project's."""
+    platform = platform or sys.platform
+    env = os.environ if env is None else env
+    # a relative value is ignored, as the XDG spec says (a quoted `~/.config` is relative too): never "no list"
+    if platform == "win32":
+        appdata = env.get("APPDATA", "")
+        base = Path(appdata) if appdata and _absolute(appdata, platform) else Path.home() / "AppData" / "Roaming"
+    else:
+        xdg = env.get("XDG_CONFIG_HOME", "")
+        base = Path(xdg) if xdg.startswith("/") else Path.home() / ".config"
+    return base / "passioncode-fabric" / LIST_NAME
+
+
+def _list_path(given: Optional[str]) -> Tuple[Optional[Path], bool]:
+    """The owner's list and whether it must be read (a named or an existing default list; else no list)."""
+    named = given or os.environ.get("FABRIC_INSTANCE_STRINGS")
+    if named:
+        try:
+            return Path(named).expanduser(), True
+        except (RuntimeError, KeyError):  # `~user` with no such user (KeyError on 3.9): never "no finding"
+            raise CheckError("the owner's list cannot be read")
+    try:
+        default = default_list()
+    except (RuntimeError, KeyError):  # no HOME and no account entry (a container's arbitrary user)
+        raise CheckError("there is no home folder to find the owner's list in: set an absolute XDG_CONFIG_HOME (APPDATA on "
+                         "Windows) or name the list with --instance-strings")
+    try:
+        os.stat(str(default))
+    except (FileNotFoundError, NotADirectoryError):
+        # a link to a list, its folder or the configuration folder on a volume not mounted: there, but not reachable
+        if any(os.path.lexists(str(p)) and not os.path.exists(str(p)) for p in (default, *default.parents)):
+            raise CheckError("the owner's list in your configuration folder cannot be read")
+        return None, False
+    except OSError:  # a list that is there but cannot be reached is not "no list": that would fail open
+        raise CheckError("the owner's list cannot be read")
+    return default, True
+
+
+class _Parser(argparse.ArgumentParser):
+    def error(self, message: str) -> NoReturn:  # argparse would repeat the arguments it could not read
+        self.print_usage(sys.stderr)
+        self.exit(2, "fabric_source_check.py: the arguments cannot be read; see the usage above\n")
+
+
+def _print(text: str) -> None:
+    """Print a line the console may not encode (a name in another script, a byte Git kept as a surrogate)."""
+    encoding = getattr(sys.stdout, "encoding", None) or "utf-8"
+    print(text.encode(encoding, "backslashreplace").decode(encoding, "replace"))
+
+
+def run_check(argv: Optional[List[str]], check: Callable[..., Dict[str, object]], read_list: Callable[[Path], List[str]],
+              ignore_globs: Callable[[Path, List[str]], List[str]], home_entry: str) -> int:
+    """The command line, run with the check's own functions (fabric_source_check.run passes them)."""
+    parser = _Parser(prog="fabric_source_check.py", description="Find instance data in an agent's source.")
+    sub = parser.add_subparsers(dest="command", required=True)
+    cmd = sub.add_parser("check", help="read the source tree and report instance data without repeating it")
+    cmd.add_argument("root", nargs="?", default=".", help="the folder to check (default: the current folder)")
+    cmd.add_argument("--instance-strings", metavar="FILE", help="the owner's list (default: FABRIC_INSTANCE_STRINGS, else "
+                     "passioncode-fabric/%s in the user's configuration folder)" % LIST_NAME)
+    cmd.add_argument("--exclude", action="append", default=[], metavar="GLOB",
+                     help="leave matching paths out, as a .fabric-source-ignore line does (repeatable)")
+    cmd.add_argument("--json", action="store_true", help="one JSON object: mode, files, findings, notRead, skipped, "
+                     "dependencies, instanceStrings, ownerHomes, instanceList, blocking, complete; exit 0 clean and "
+                     "complete, 1 a finding, 2 a file not read or no run")
+    cmd.add_argument("--every-file", action="store_true", help="read every file, not only what Git would commit")
+    try:
+        args = parser.parse_args(argv)
+    except SystemExit as exc:  # --help, or arguments argparse refused: the exit code, as the command line gives it
+        return exc.code if isinstance(exc.code, int) else 2
+    try:
+        try:
+            root = Path(args.root).expanduser().resolve()
+            is_folder = root.is_dir()
+        except (OSError, RuntimeError, KeyError):  # a parent it cannot search, a symlink loop, `~` with no home
+            raise CheckError("the folder cannot be read")
+        if not is_folder:
+            raise CheckError("ROOT is not a folder")
+        list_path, _ = _list_path(args.instance_strings)  # may raise CheckError
+        entries: List[str] = []
+        if list_path is not None:
+            try:
+                resolved = list_path.resolve()
+            except (OSError, RuntimeError):  # RuntimeError: Python 3.9's symlink loop
+                raise CheckError("the owner's list cannot be read")
+            if resolved == root or root in resolved.parents:
+                raise CheckError("the owner's list is inside the tree it checks, where it would travel with the source; "
+                                 "keep it in your configuration folder (passioncode-fabric/%s)" % LIST_NAME)
+            try:
+                present = resolved.is_file()
+            except OSError:
+                raise CheckError("the owner's list cannot be read")
+            if not present:
+                raise CheckError("the owner's list named by --instance-strings or FABRIC_INSTANCE_STRINGS does not exist or is "
+                                 "not a regular file"
+                                 if args.instance_strings or os.environ.get("FABRIC_INSTANCE_STRINGS")
+                                 else "the owner's list in your configuration folder is not a file")
+            try:
+                entries = read_list(resolved)
+            except UnicodeDecodeError:
+                raise CheckError("the owner's list is not UTF-8")
+            except OSError:
+                raise CheckError("the owner's list cannot be read")
+        result = check(root, entries, ignore_globs(root, args.exclude), args.every_file)
+    except CheckError as exc:
+        print("fabric_source_check.py: %s" % exc, file=sys.stderr)
+        return 2
+    if result.get("manifest"):  # under fabric.source.json: its own report (fabric_source_tree.print_run)
+        return sys.modules["fabric_source_tree"].print_run(result, entries, list_path is not None, args.json, _print)
+    findings = result["findings"]
+    skipped = result["skipped"]
+    listed = sum(1 for e in entries if e and not e.startswith(home_entry))
+    homes = sum(1 for e in entries if e.startswith(home_entry))
+    # a binary file is not read either: it is complete only when every one is named as source in the ignore file
+    complete = not (skipped["unreadable"] or skipped["binary"] or skipped["nested"])  # type: ignore[index]
+    result.update({"instanceStrings": listed, "ownerHomes": homes, "instanceList": list_path is not None, "blocking": bool(findings),
+                   "complete": complete})
+    if args.json:
+        _print(json.dumps(result, indent=2))
+    else:
+        for f in findings:  # type: ignore[union-attr]
+            _print("%s:%s: %s (%s)" % (f["path"], f["line"], f["kind"], f["rule"]))
+        for n in result["notRead"]:  # type: ignore[union-attr]
+            _print("%s: not read (%s)" % (n["path"], n["why"]))
+        for folder in result["dependencies"]:  # type: ignore[union-attr]
+            _print("%s: not read (a dependency folder; --every-file reads it)" % folder)
+        if skipped["dependencies"]:  # type: ignore[index]
+            _print("%d dependency folder(s) not read (node_modules, virtual environments, caches); --every-file reads "
+                   "them" % skipped["dependencies"])  # type: ignore[index]
+        _print("%d file(s) read (%s), %d finding(s); not read: %d binary, %d unreadable, %d nested repository; "
+               "%d left out by name; %d instance string(s) listed%s%s"
+               % (result["files"], "what Git would commit" if result["mode"] == "git" else
+                  "every file, as pack reads them" if args.every_file else "every file but dependency folders, Git not used",
+                  len(findings), skipped["binary"], skipped["unreadable"], skipped["nested"],  # type: ignore[index]
+                  skipped["excluded"], listed,  # type: ignore[index]
+                  "" if listed or homes else (" (the owner's list holds no string of three or more characters)"
+                                              if list_path else " (no owner's list)"),
+                  "; %d home name(s) declared" % homes if homes else ""))
+    if findings:
+        return 1
+    return 0 if complete else 2

package/plugins/fabric-agent-adapter/skills/building-fabric-services/SKILL.md

@@ -6,10 +6,10 @@ description: >-
   for a provider manifest (adapting-projects-to-fabric), a new agent (creating-fabric-agents) or a session
   (working-with-fabric).
 license: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
-compatibility: Python 3.9+ or Node.js 20+ for the kits (Node.js 22+ for a Linux service's instance lock); the probe needs Python 3.9+. launchd steps are macOS-only; Linux services install a systemd user unit and Windows ones a per-user Scheduled Task with the kits' writers. Dashboard handoff optionally uses Fabric Dashboards MCP link/host_status/open; without it, report unresolved host capability. The contract checkout is optional.
+compatibility: Python 3.9+ or Node.js 20+ for the kits (Node.js 22+ for a Linux service's instance lock); the probe needs Python 3.9+. launchd steps are macOS-only; Linux services install a systemd user unit and Windows ones a per-user Scheduled Task with the kits' writers. Dashboard handoff optionally uses Fabric Dashboards MCP link/host_status/open; without it, report unresolved host capability. The contract checkout is optional. On macOS 27.2 run kit services and the probe on Apple's /usr/bin/python3.
 metadata:
   author: PassionCode.ai
-  version: "0.82.0"
+  version: "0.83.1"
   contract-version: "0.1.0"
   extension: "fabric-service/0.1"
   extension-commit: "93e7db164c7829e2783b4b7705c4113bb5201131"
@@ -52,7 +52,8 @@ to review one. Do not use it for:
 
 It is a service when at least one is true: other agents call it while the operator is
 away; it runs jobs longer than one request; it owns a store other tools read; the
-operator watches it on a page. Otherwise build a CLI and stop here.
+operator watches it on a page; it is an uptime A agent that answers while the owner's computer is off (an online
+service, the remote placement below). Otherwise build a CLI and stop here.
 
 Answer before writing code, and record the answers in the project README:
 
@@ -73,7 +74,7 @@ Answer before writing code, and record the answers in the project README:
 | Another agent on this machine | MCP `2026-07-28`, `streamable-http`, at `/mcp` on the service origin, token in a header | one process serves every session; `mcp-register` checks the listener (HA-2) first |
 | The operator or a script | a CLI: `<tool> service status\|start\|stop\|restart`, `<tool> dashboard` (opens only in Fabric Dashboards, below), `<tool> doctor --json` | every verb delegates to launchd and the well-known document, never to its own process table |
 | A remote agent | A2A `1.0` over HTTPS, or MCP behind an authenticated gateway | loopback reachability is not authorization |
-| An A2A peer on this computer | `surfaces.a2a` names a public Agent Card, served without the token; its interface URLs are loopback (DEC-0122); the kits read it, serving one is FAA-10 | the card carries no credential, process member or required Fabric extension |
+| An A2A peer on this computer | `surfaces.a2a` names a public Agent Card, served without the token; its interface URLs are loopback (DEC-0122); the kits read it and serve one with the JSON-RPC binding ([the A2A reference](references/a2a.md)) | the card carries no credential, process member or required Fabric extension |
 | The dashboard page | same-origin REST under `/api`, session cookie plus a custom request header; every button on it also a tool on the MCP surface (Step 5) | the existing dashboards' CSRF defence |
 
 Read [the surfaces and auth reference](references/surfaces-and-auth.md) when wiring
@@ -105,6 +106,7 @@ When the service answers requests other Projects post to its Project on Fabric's
 responder in its own process: [`scripts/fabric_hub.py`](scripts/fabric_hub.py) finds the hub and joins,
 [`scripts/fabric_board.py`](scripts/fabric_board.py) enrolls, claims, accepts the exact digest, checkpoints before
 every step and stops on `fenced`, `lease_expired` or `authority_changed` (Node: `fabric-hub.mjs`, `fabric-board.mjs`).
+It reads an operator's mandate on a request only when it opts in with `agent_id=` and `mandate_from=` (Node: `agentId`, `mandateFrom`).
 The request body is data behind the service's own input gate. A slot moved to another
 session stays moved until `take_back` (`takeBack`) or a move back once Fabric offers one: give it an operator action with its tool and gate
 `relayed` (the operator reaches it through an agent that relays their decision in `_meta`, the service's
@@ -172,7 +174,8 @@ spend ceiling before every attempt, receipts and a fallback). The draft-and-chec
 support agent on the kit: [`recipes/support-agent/`](recipes/support-agent/README.md); the whole agent:
 creating-fabric-agents' `references/agents-that-answer-people.md`. A service that is only a dashboard:
 [`recipes/dashboard-only/`](recipes/dashboard-only/README.md); a door that hands a key on sealed:
-[`recipes/key-delivery-door/`](recipes/key-delivery-door/README.md).
+[`recipes/key-delivery-door/`](recipes/key-delivery-door/README.md); numbers computed by code from a read-only
+source: [`recipes/data-agent/`](recipes/data-agent/README.md).
 
 Startup order is the part that goes wrong; keep it exactly:
 
@@ -228,7 +231,7 @@ The installer, not the service, owns the plist and the descriptor. Sequence:
    FileVault restart) install a LaunchDaemon instead: the plist in `/Library/LaunchDaemons` with `user_name`, as root
    (the lifecycle reference, *The system domain*).
 3. Uninstall: `launchd_uninstall` (waits for the unload, removes the plist, resets the
-   override; `purge=True` removes data only when the operator asks), `remove_descriptor`.
+   override; `purge=True` removes data only when the operator asks, and a LaunchDaemon refuses it), `remove_descriptor`.
 4. After an upgrade, `prune_releases(releases_dir, current=…)` keeps the running release
    and the one before it.
 
@@ -268,6 +271,9 @@ agents, models, connectors, stores and channels, each with its state, from
 `connections_extension()` / `connectionsExtension()` in `fabric_connections`. Never a credential in it, never a call
 count (that is the usage report); details: [the wire reference](references/protocol.md).
 
+A service counts its own log into hourly and daily **operations digests** (DEC-0153) with `fabric_ops_digest`
+(`fabric-ops-digest.mjs`): [the ops digest reference](references/ops-digest.md).
+
 The events feed is a **view over the log you already keep** (a jobs table, a JSONL
 journal), not a second store. Each event is one sentence a person reads; set
 `notify: true` only when the operator must decide, or something failed or degrades their
@@ -355,7 +361,8 @@ Whoever owns the repository, an agent with a page gets the dashboard rule block
 (below). org-index `scripts/check_format.py` reports 0 findings for it before it is called done. **An agent
 someone builds for themselves is not a PassionCode.ai repository:** its licence is its owner's choice, the organization
 publishes and lists nothing about it, of these files one built new needs only a `LICENSE` naming its copyright holder (copied kit files keep
-theirs), and the verified MCP quick start teaches anyone to drive it.
+theirs), and the verified MCP quick start teaches anyone to drive it. The kit's files stay AGPL-3.0-only or the
+PassionCode commercial licence there, in an agent built for a client too.
 
 ## Online services: the remote placement
 
@@ -421,7 +428,7 @@ this estate needs.
   explicitly in the plist; never copy the whole shell environment into it.
 - A plist pointing at a worktree or checkout breaks when it moves: point it at a release.
 - `http.server.HTTPServer` resolves its FQDN between `bind()` and `listen()`: with a slow
-  resolver (a macOS CI runner, a Mac offline) the port is bound but silent. Use `fs.LoopbackHTTPServer`.
+  resolver (a macOS CI runner, a Mac offline) the port is bound but silent: connects time out. Use `fs.LoopbackHTTPServer`.
 - `logging.basicConfig` called twice: the second is a no-op and the log stays empty. Configure logging once, in
   the entry point.
 - Hand-made `.plist.bak` files in `~/Library/LaunchAgents` are never cleaned up; keep

package/plugins/fabric-agent-adapter/skills/building-fabric-services/assets/dashboard-kit/fabric-button.js

@@ -1,4 +1,4 @@
-/* fabric-dashboard-kit@1.1.7 · Fabric's button (Fabric Agent Contract DEC-0040, FB-1…FB-8, FL-1…FL-6)
+/* fabric-dashboard-kit@1.1.8 · Fabric's button (Fabric Agent Contract DEC-0040, FB-1…FB-8, FL-1…FL-6)
    Load it same-origin, after fabric-dashboard.css, with the service it opens Fabric on:
      <script src="fabric-button.js" defer data-service="example-agent.default" data-service-name="Example Agent"
              data-project="project-a" data-project-name="Project A"></script>
@@ -11,7 +11,7 @@
 (function (root) {
   'use strict';
 
-  var VERSION = '1.1.7';
+  var VERSION = '1.1.8';
   var COOKIE = 'fabric_button';
   var GET_FABRIC = 'https://passioncode.ai/fabric';
   var ABSENT_AFTER_MS = 1500;
@@ -178,7 +178,7 @@
   }
 
   // The words a person reads (FAA-119): English, or Russian on a page whose lang is ru; the Russian is written as
-  // escapes so the file reads the same whatever charset it is served with. Checked with Copylot (en-US and ru-RU).
+  // escapes so the file reads the same whatever charset it is served with. Checked with the copy checker (en-US and ru-RU).
   var LABELS = {
     en: { chat: 'Chat with Fabric about {name}', session: 'Open a coding session in {name}', open: 'Open Fabric',
       absent: 'Fabric is not installed. Get it at' },

package/plugins/fabric-agent-adapter/skills/building-fabric-services/assets/dashboard-kit/fabric-dashboard.css

@@ -1,4 +1,4 @@
-/* fabric-dashboard-kit@1.1.7 · fabric-dashboard/0.1 (Fabric Agent Contract DEC-0036)
+/* fabric-dashboard-kit@1.1.8 · fabric-dashboard/0.1 (Fabric Agent Contract DEC-0036)
    A Fabric service dashboard shown inside a host pane: usable from 360 CSS px up, navigation always
    reachable, wide content in its own scroll box, one vertical scroller, appearance from the host.
    Copy this file next to fabric-dashboard.js; do not edit it in place. Put the page's own rules in

package/plugins/fabric-agent-adapter/skills/building-fabric-services/assets/dashboard-kit/fabric-dashboard.js

@@ -1,4 +1,4 @@
-/* fabric-dashboard-kit@1.1.7 · fabric-dashboard/0.1 (Fabric Agent Contract DEC-0036)
+/* fabric-dashboard-kit@1.1.8 · fabric-dashboard/0.1 (Fabric Agent Contract DEC-0036)
    Load it same-origin with <script src="fabric-dashboard.js" defer></script>: no inline script, no
    eval, nothing from a CDN. It applies the host's appearance (ED-6, ED-8), folds navigation that
    does not fit into a More menu (ED-3), makes wide boxes keyboard-reachable (ED-4) and keeps
@@ -8,7 +8,7 @@
   'use strict';
 
   var KIT = 'fabric-dashboard-kit';
-  var VERSION = '1.1.7';
+  var VERSION = '1.1.8';
   /* fabric-dashboard-kit:theme-ids:begin */
   var THEMES = ['graphite', 'fabric', 'paper', 'forest', 'ocean', 'ember', 'contrast'];
 /* fabric-dashboard-kit:theme-ids:end */

package/plugins/fabric-agent-adapter/skills/building-fabric-services/assets/dashboard-kit/kit.json

@@ -1,6 +1,6 @@
 {
   "name": "fabric-dashboard-kit",
-  "version": "1.1.7",
+  "version": "1.1.8",
   "profile": "fabric-dashboard/0.1",
   "decision": "DEC-0036",
   "declarationKey": "https://fabric.passioncode.ai/agent-contract/extensions/dashboard/0.1",
@@ -15,9 +15,9 @@
     "contrast"
   ],
   "files": {
-    "fabric-dashboard.css": "549c1c1546bc9f8d2c1a579e7ad1035d009c94c3324b91d89d892afc437d5800",
-    "fabric-dashboard.js": "fa966a8f3b228391c2dae33674887a0d44b102cb58e42dbe6331f08bab57b391",
-    "fabric-button.js": "220c5c9719a9f6e35851d8748e2abb1d6606ffdb9fc43f3aff2b01f34637d925",
+    "fabric-dashboard.css": "0c58c2758e780f4f520d3ea45d69a7d4221ad97cdc7e6999da7c7511e6beb96c",
+    "fabric-dashboard.js": "dfaef6b91102817061f612aea1f4b5a85699a890d7f4fbda2780dc153f2e5da1",
+    "fabric-button.js": "11ebad0cc598b09f034666be377caf0edc0042e9e86d7d8e8292dda57789be7f",
     "themes.json": "511839f1a1a83eb37fadfd132791474497d5c28c5091700b9aa31ad076e359b5"
   },
   "history": {
@@ -64,6 +64,11 @@
       "fabric-dashboard.css": "549c1c1546bc9f8d2c1a579e7ad1035d009c94c3324b91d89d892afc437d5800",
       "fabric-dashboard.js": "fa966a8f3b228391c2dae33674887a0d44b102cb58e42dbe6331f08bab57b391",
       "fabric-button.js": "220c5c9719a9f6e35851d8748e2abb1d6606ffdb9fc43f3aff2b01f34637d925"
+    },
+    "1.1.8": {
+      "fabric-dashboard.css": "0c58c2758e780f4f520d3ea45d69a7d4221ad97cdc7e6999da7c7511e6beb96c",
+      "fabric-dashboard.js": "dfaef6b91102817061f612aea1f4b5a85699a890d7f4fbda2780dc153f2e5da1",
+      "fabric-button.js": "11ebad0cc598b09f034666be377caf0edc0042e9e86d7d8e8292dda57789be7f"
     }
   }
 }