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

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

@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+# SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 """The contract's one credential detector (Fabric Agent Contract DEC-0044, `src/secret-shape.ts` at the pin): a name
 that can only carry a credential, a value shaped like one, a launch argument that carries one, and a URL that does
 (LC-21). A port held to the contract's own answers by test/fixtures/contract/profile-vectors.json. Standard library
@@ -31,7 +32,7 @@ CREDENTIAL_PAIRS: Dict[str, tuple] = {
 }
 #: ECMAScript's \s, as a character class body.
 JS_SPACE = "\t\n\x0b\x0c\r \xa0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff"
-_NOT_LINE_END = "[^\n\r\u2028\u2029]"  # ECMAScript's `.` without the s flag
+NOT_LINE_END = "[^\n\r\u2028\u2029]"  # ECMAScript's `.` without the s flag
 JWT_SHAPE = re.compile(r"eyJ[A-Za-z0-9_-]{2,}\.[A-Za-z0-9_-]{2,}\.[A-Za-z0-9_-]*")
 _URL_BASE64_RUN = re.compile(r"[A-Za-z0-9_-]*")
 
@@ -74,14 +75,17 @@ _PROVIDER_KEYS = (r"(?:sk-(?=[A-Za-z0-9_-]{0,255}?[0-9])(?:(?=[A-Za-z0-9_-]{0,25
 #: The contract's SECRET_VALUE at the pin (DEC-0151): `Bearer ` at a value's start in any case, or a provider key after a
 #: boundary. No case-insensitive flag; digits are ASCII. A match includes its boundary character: callers test, never
 #: read the matched text or its index.
-SECRET_VALUE = re.compile("(^[Bb][Ee][Aa][Rr][Ee][Rr][" + JS_SPACE + "]" + _NOT_LINE_END + "+|" + _KEY_BOUNDARY + _PROVIDER_KEYS + ")")
+SECRET_VALUE = re.compile("(^[Bb][Ee][Aa][Rr][Ee][Rr][" + JS_SPACE + "]" + NOT_LINE_END + "+|" + _KEY_BOUNDARY + _PROVIDER_KEYS + ")")
 _LONG_RUN = re.compile(r"[A-Za-z0-9+/=_-]{40,}")
-_BEARER_INSIDE = re.compile(r"(?<![A-Za-z0-9_])bearer[%s]+(?=[A-Za-z0-9._~+/-]*[0-9])[A-Za-z0-9._~+/-]{12,}=*" % JS_SPACE,
+BEARER_INSIDE = re.compile(r"(?<![A-Za-z0-9_])bearer[%s]+(?=[A-Za-z0-9._~+/-]*[0-9])[A-Za-z0-9._~+/-]{12,}=*" % JS_SPACE,
                             re.IGNORECASE | re.ASCII)
 _PATH_LIKE = re.compile(r"^(?:[/~.]|[A-Za-z]:[\\/]|[a-z][a-z0-9+.-]*://)", re.IGNORECASE | re.ASCII)
 _WORD_SPLIT = re.compile("[%s._-]+" % JS_SPACE)
 _ARGUMENT_SPLIT = re.compile("[%s=]" % JS_SPACE)
-_SCHEME = re.compile(r"^[A-Za-z][A-Za-z0-9+.-]*:")
+SCHEME = re.compile(r"^[A-Za-z][A-Za-z0-9+.-]*:")
+#: The names the check and older readers wrote before these became public (FAA-190 (2), (12)): kept so a module from
+#: an earlier version beside this one still loads.
+_BEARER_INSIDE, _SCHEME, _NOT_LINE_END = BEARER_INSIDE, SCHEME, NOT_LINE_END
 #: WHATWG's special schemes that carry an authority with user information (file has none).
 _SPECIAL = ("ftp", "http", "https", "ws", "wss")
 
@@ -108,13 +112,17 @@ def credential_name(name: str) -> bool:
     return any(word in words and any(p in words for p in partners) for word, partners in CREDENTIAL_PAIRS.items())
 
 
-def _long_secret(value: str) -> bool:
+def long_secret(value: str) -> bool:
+    """A run of 40 or more base64 characters mixing upper case, lower case and digits (the Node twin's longSecret)."""
     return any(re.search(r"[a-z]", run) and re.search(r"[A-Z]", run) and re.search(r"[0-9]", run) for run in _LONG_RUN.findall(value))
 
 
+_long_secret = long_secret  # its name before FAA-190 (2)
+
+
 def secret_value(value: str) -> bool:
     """A JWT anywhere, a provider key or `Bearer …`, or a long base64 run mixing upper case, lower case and digits."""
-    return bool(has_jwt(value) or SECRET_VALUE.search(value) or _long_secret(value))
+    return bool(has_jwt(value) or SECRET_VALUE.search(value) or long_secret(value))
 
 
 def _path_like(piece: str) -> bool:
@@ -126,13 +134,13 @@ def _path_like(piece: str) -> bool:
 def secret_argument(value: str) -> bool:
     """The same for a launch argument or a server's command and URL: a long run is looked for between path separators,
     so a folder path holding a session id is not taken for a key."""
-    if has_jwt(value) or SECRET_VALUE.search(value) or _BEARER_INSIDE.search(value):
+    if has_jwt(value) or SECRET_VALUE.search(value) or BEARER_INSIDE.search(value):
         return True
     for piece in _ARGUMENT_SPLIT.split(value):
         if _path_like(piece):
-            if any(_long_secret(part) for part in re.split(r"[\\/]", piece)):
+            if any(long_secret(part) for part in re.split(r"[\\/]", piece)):
                 return True
-        elif _long_secret(piece):
+        elif long_secret(piece):
             return True
     return False
 
@@ -421,7 +429,7 @@ def _url_credential(value: str, hosts: bool) -> bool:
     # What WHATWG URL parsing does first: trim C0 controls and space from the ends (never other Unicode spaces, which it
     # refuses), then remove every tab, CR and LF.
     value = re.sub(r"[\t\n\r]", "", value.strip(_C0_OR_SPACE))
-    if not _SCHEME.match(value):
+    if not SCHEME.match(value):
         return False  # not an absolute URL (WHATWG URL parsing refuses it)
     if hosts and url_refused(value):
         return False  # `new URL` refuses its host or port, so the Node twin reads it as an argument only (FAA-309)
@@ -442,7 +450,25 @@ _REPOSITORY_AUTHORITY = re.compile(r"[A-Za-z][A-Za-z0-9+.-]*://")
 #: boundary, so composed after a separator look-behind it would miss a key after `-`, `.` or `_`.
 _REPOSITORY_KEYS = r"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,}"
 _KEY_AT_A_WORD = re.compile(r"(?:\A|(?<=[._-]))(?:%s)" % _REPOSITORY_KEYS)
-_JWT_AT_A_WORD = re.compile(r"(?:\A|(?<=[._-]))%s" % JWT_SHAPE.pattern)
+
+
+def jwt_at_a_word(text: str) -> bool:
+    """Whether JWT_SHAPE matches at a word's start: the text's start, or after a `.`, `_` or `-` (FAA-321). Read in one
+    pass, as jwt_spans: the look-behind expression backtracked from every such `eyJ` of a long run, quadratic in it.
+    Every `eyJ` of one run shares that run's end and a shorter first segment, so only a run's first `eyJ` at a word's
+    start is tried; an `eyJ` that is not at one is passed over, since a later one of its run may be."""
+    at = text.find("eyJ")
+    while at >= 0:
+        if at and text[at - 1] not in "._-":
+            at = text.find("eyJ", at + 1)
+            continue
+        one = _URL_BASE64_RUN.match(text, at + 3).end()
+        if one - at - 3 >= 2 and text[one:one + 1] == ".":
+            two = _URL_BASE64_RUN.match(text, one + 1).end()
+            if two - one - 1 >= 2 and text[two:two + 1] == ".":
+                return True
+        at = text.find("eyJ", one)
+    return False
 
 
 def repository_name(piece: str) -> bool:
@@ -450,7 +476,7 @@ def repository_name(piece: str) -> bool:
     key's or JWT's shape (`sk-`, `ghp_`, `xoxb-`, `AKIA`, `eyJ`) at its start or after a `.`, `_` or `-` (0.62.0
     readings 9 and 10), so a letters-only key is still a key while `task-pipeline-dashboard`, which holds an `sk-` shape
     inside a word, is a name."""
-    return bool(_REPOSITORY_NAME.match(piece)) and not _KEY_AT_A_WORD.search(piece) and not _JWT_AT_A_WORD.search(piece)
+    return bool(_REPOSITORY_NAME.match(piece)) and not _KEY_AT_A_WORD.search(piece) and not jwt_at_a_word(piece)
 
 
 def ascii_decoded(text: str) -> str:

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.84.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, each service kit module in its own SPDX line), 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