@passioncode-ai/fabric-agent-adapter 0.79.1 → 0.81.0

package/plugins/fabric-agent-adapter/skills/adapting-projects-to-fabric/references/source-and-instance.md

@@ -7,13 +7,15 @@ first commit, so that its owner can hand the source over later without rewriting
 by itself: handing over, a new remote, a push or a change of visibility stays the owner's act, each time (a personal
 agent stays private until its owner says so about that act).
 
-The format of a source manifest, export and import is the contract's to decide (CT-194). What follows does not depend
-on it.
+The format of a source manifest, export and import is the contract's: DEC-0149 (`fabric-source/1`, its `source.md`) at
+the pin. The kit lays down `fabric.source.json` ([the source manifest](#the-source-manifest)), and the check reads the
+source under it.
 
 ## Contents
 
 - [The layout](#the-layout)
 - [The data home and its kind](#the-data-home-and-its-kind)
+- [The source manifest](#the-source-manifest)
 - [The check](#the-check)
 
 ## The layout
@@ -42,11 +44,11 @@ on it.
 - **Fixtures on neutral ids.** A test that needs a home folder, an owner or an account uses `example`, `example-agent`,
   `owner@example.com` or a one-letter home, and a credential-shaped test value says it is synthetic
   (`sk-test-not-a-key`) or is assembled at run time.
-- **Two names stay in the source until the contract decides (CT-194).** A service's supervisor label is the agent's
-  own name, reverse-DNS on the publisher's domain (`com.example.example-agent`), and `AGENTS.md` names it (LC-09):
-  never the owner's account or name. A provider's `createdBy` names the publisher; until one is chosen it
-  keeps the scaffold's sentinel, and a person's name or account is never written there. The adapter moves both when the
-  contract decides how an instance renames them (FAA-188 part 2).
+- **Two names are slots, never values (DEC-0149, FAA-188 part 2).** A service's supervisor label is the agent's own
+  name, reverse-DNS on the publisher's domain (`com.example.example-agent`), and `AGENTS.md` names it (LC-09): never the
+  owner's account or name; the label an installation runs under is its `SUPERVISOR_LABEL` slot, with its port in
+  `SERVICE_PORT`. A provider's `createdBy` names the publisher; the source keeps the scaffold's sentinel, and the
+  publisher's URI is the installation's `PUBLISHER_URI` slot, so a person's name or account is never written there.
 
 ## The data home and its kind
 
@@ -69,6 +71,41 @@ on it.
   configuration and dependency folders `--every-file` reads too), each exit 0, with the owner's list or its absence recorded, until the contract's export (CT-194)
   replaces it.
 
+## The source manifest
+
+`fabric.source.json` at the source's root says what is source and which slots an installation fills, never a value
+(DEC-0149, `fabric-source/1`):
+
+| Member | What |
+|---|---|
+| `include` | the source, default deny: a file outside every entry is not source; an entry ending in `/` is a folder, no globs |
+| `exclude` | holes in `include`, read in any letter case and Unicode form (a file an entry names only in another spelling is left out, and the check says `excluded-by-fold`) |
+| `binaries` | the binary files that are source (an icon, a font); another binary blocks |
+| `unchecked` | source paths that travel unread, each with its reason (synthetic test vectors, a licence naming a holder on the owner's list) |
+| `publicAddresses` | the e-mail addresses the source may carry (a support address); another one warns |
+| `slots` | what an installation fills, by name: `secret` (a key), `config` (a setting: a repository URL, a folder, the supervisor label, the publisher's identity), `store` (a data store, with its path in the data folder), `endpoint` (the operator's infrastructure by role) |
+
+- **Laying it down.** A new agent gets it from `new_agent.py` (creating-fabric-agents' `references/new-agent.md`); an
+  existing project from `adapt_project.py source <project-root>` (adapting-projects-to-fabric's scripts), which proposes `include` from the
+  project's top-level entries (what Git would commit, instance data by its name left out) and names the kit's slots
+  (`PUBLISHER_URI` where a provider manifest is there, `PLACEMENT_RECORD`, and with `--service` `SUPERVISOR_LABEL` and
+  `SERVICE_PORT`); `--secret NAME:PURPOSE` and `--store NAME:PATH:PURPOSE` add the agent's own. `--dry-run` prints the
+  proposal and writes nothing; an existing manifest is the owner's and is replaced only with `--force`. The author then
+  narrows `include` to what is source.
+- **The check under it.** When the folder it checks holds `fabric.source.json`, `fabric_source_check.py check` reads
+  the source the manifest names and reports the contract's kinds (`fabric_source_tree.py`, held to the contract's
+  vectors): blocking `home-path`, `credential`, `binary`, `nested-repository`, `instance-string`, `missing`,
+  `no-include` and the manifest's own findings (FAC-SEM-156, FAC-SEM-157); warnings `email`, `link-outside`,
+  `no-license`, `unused-exclude`, `excluded-by-fold`, each by path, line and column (UTF-16 units), never by the text
+  found. Exit 1 on a blocking finding, 0 when only warnings remain and every source file was read, 2 when one was not.
+  `.fabric-source-ignore` and `--exclude` are not read there: `exclude` and `unchecked` say it. A declared home
+  (`home: <name>`) is still found in every source file.
+- **Packing it.** `pack` (building-fabric-services' `references/package.md`) writes the package's `secrets[]` from the secret slots and `state[]` from the store slots' paths, and refuses a
+  package whose members differ (FAC-SEM-160); an empty `state[]` is a copy packed without state, and stays so. A
+  hand-written `secrets[]` naming a secret the manifest has no slot for is refused by name, never dropped.
+- **Handing it over** stays the owner's act, each time, on their word for that act (the contract's `source.md`,
+  Handing over).
+
 ## The check
 
 `fabric_source_check.py check` reads the files the source would carry (what Git would commit: tracked files and

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

@@ -22,10 +22,10 @@ import fabric_secrets as _secrets  # noqa: E402 - the contract's credential dete
 
 CONTRACT_VERSION = "0.1.0"
 CONTRACT_REPOSITORY = "https://github.com/passioncode-ai/fabric-agent-contract"
-CONTRACT_COMMIT = "18f8d48762edc5bfb1433657cbfe1c16196df1a6"
+CONTRACT_COMMIT = "93e7db164c7829e2783b4b7705c4113bb5201131"
 # #region supported-contract-revisions — docs: README.md#contract-pin
 # Only this declaration may name a legacy revision in live files.
-SUPPORTED_CONTRACT_COMMITS = (CONTRACT_COMMIT, "eac1a594aa131851f079da8bb7b2149e1951f35f", "3830a3353923e20f826d466610e1c479f120bec0", "00e050ba7429c0c60261cec871779e0fd6aeeb28", "1197a90dc4b57152cabcc71ad17db7559f35a27f", "e6c4fc16b415eec3190dd34d924d269405359dc9", "a3a66eb0052043847f6556348e37d34ca873a629", "52c7d798b9f4eb784eb4e29e717038a8912c759d", "2f020a696453ae299b123517f14957f6a1354379", "87d384ffce2757081b7ab227e5dad3dddd08328f", "0a4ce773c4b9e6bec40c6387eb3f988af7152c0e", "e742016dc396aa31e5a13a893489e43f15786c69", "bfa9a67aa3c6cb808c093e7d83cd59799f1ee7d0", "c55f2d5a11c9a0197e958e87212fca7ae1154769", "07042181bfae2a481aa0da1a5651f24c76669c48", "d8146cfb0a1c74fc6432284c4356bb0c864b37b5", "82e163665e156a08aa3b92e4711015582c06162c", "1636fa97262f4a26e2086572d540c2ee701e0010", "f00a7685e3861c27f7899c033fb850a145a1708f", "a046f57cf46ea9e3da57ff8ce6a3ed4d26d8774b", "fe55fc67cba1a9e34a736da7d148d4fe2a8fbfa0", "b291bf09e0a9f9fd3c16cf540832cd021203b7d1", "0cacd08b0e95b6abf131eae1206b60792138bc3c", "2eb91c00e852d9c31d804310d38fad91589fcbac", "8e49fbd5fbbf230e32c1969cd24ac3c22422f0a5", "a83bec6b47776af688402c18efec507143061f68", "52da526d7cc1e063d74c5b520dbc03d0ace15246", "78b2da018d2c4bd9ac1bde1dc3b7f1a110a175f5", "623bf61358c339cb10297807b3f024b5d9f1f327", "23f9fda4c05f8a3852246ee98d4f2adf74ed0875", "9091d3d6606b0c4b5591a38c3674356a01fd7f55", "df55c8c54a23251342a7ee57ba95642b7eb39e61", "2ce392291c6668598d12cd38327e24696b5ca15c")
+SUPPORTED_CONTRACT_COMMITS = (CONTRACT_COMMIT, "18f8d48762edc5bfb1433657cbfe1c16196df1a6", "eac1a594aa131851f079da8bb7b2149e1951f35f", "3830a3353923e20f826d466610e1c479f120bec0", "00e050ba7429c0c60261cec871779e0fd6aeeb28", "1197a90dc4b57152cabcc71ad17db7559f35a27f", "e6c4fc16b415eec3190dd34d924d269405359dc9", "a3a66eb0052043847f6556348e37d34ca873a629", "52c7d798b9f4eb784eb4e29e717038a8912c759d", "2f020a696453ae299b123517f14957f6a1354379", "87d384ffce2757081b7ab227e5dad3dddd08328f", "0a4ce773c4b9e6bec40c6387eb3f988af7152c0e", "e742016dc396aa31e5a13a893489e43f15786c69", "bfa9a67aa3c6cb808c093e7d83cd59799f1ee7d0", "c55f2d5a11c9a0197e958e87212fca7ae1154769", "07042181bfae2a481aa0da1a5651f24c76669c48", "d8146cfb0a1c74fc6432284c4356bb0c864b37b5", "82e163665e156a08aa3b92e4711015582c06162c", "1636fa97262f4a26e2086572d540c2ee701e0010", "f00a7685e3861c27f7899c033fb850a145a1708f", "a046f57cf46ea9e3da57ff8ce6a3ed4d26d8774b", "fe55fc67cba1a9e34a736da7d148d4fe2a8fbfa0", "b291bf09e0a9f9fd3c16cf540832cd021203b7d1", "0cacd08b0e95b6abf131eae1206b60792138bc3c", "2eb91c00e852d9c31d804310d38fad91589fcbac", "8e49fbd5fbbf230e32c1969cd24ac3c22422f0a5", "a83bec6b47776af688402c18efec507143061f68", "52da526d7cc1e063d74c5b520dbc03d0ace15246", "78b2da018d2c4bd9ac1bde1dc3b7f1a110a175f5", "623bf61358c339cb10297807b3f024b5d9f1f327", "23f9fda4c05f8a3852246ee98d4f2adf74ed0875", "9091d3d6606b0c4b5591a38c3674356a01fd7f55", "df55c8c54a23251342a7ee57ba95642b7eb39e61", "2ce392291c6668598d12cd38327e24696b5ca15c")
 # #endregion supported-contract-revisions
 INTEROP_KEY = "https://fabric.passioncode.ai/agent-contract/extensions/interop/0.1"
 MCP_REVISION = "2026-07-28"
@@ -488,6 +488,98 @@ def scaffold_project(root: Path, args: argparse.Namespace) -> Dict[str, Any]:
     }
 
 
+# #region source-manifest: fabric.source.json (contract DEC-0149, fabric-source/1; FAA-261)
+SOURCE_FILE = "fabric.source.json"
+_SLOT_NAME = re.compile(r"[A-Z][A-Z0-9_]{0,63}\Z")
+#: Instance data never named in include: the repository, credentials by their name, dependency and build folders.
+_NOT_SOURCE = re.compile(r"\.git|\.env(\..*)?|.*\.(pem|key|p12|pfx|jks|keystore|token|credential)|node_modules|\.venv|venv|"
+                         r"__pycache__|dist|build|\.DS_Store|" + re.escape(SOURCE_FILE), re.IGNORECASE)
+#: The slots the kit names for every agent: the provider's createdBy and, for a service, its supervisor label and port
+#: are instance data (FAA-188 part 2); the placement record is the operator's infrastructure, read at start.
+PUBLISHER_SLOT = {"name": "PUBLISHER_URI", "kind": "config",
+                  "purpose": "provider.createdBy: the publisher's URI; the source keeps the scaffold's sentinel"}
+PLACEMENT_SLOT = {"name": "PLACEMENT_RECORD", "kind": "endpoint", "optional": True,
+                  "purpose": "Project Observatory's placement record (observatory-placement/1), read at start"}
+SERVICE_SLOTS = (
+    {"name": "SUPERVISOR_LABEL", "kind": "config",
+     "purpose": "the launchd label, systemd unit or Scheduled Task this installation runs under (LC-09)"},
+    {"name": "SERVICE_PORT", "kind": "config", "purpose": "the loopback port recorded for this OS account (DEC-0154 HA-1)"},
+)
+
+
+def _parse_slot(text: str, kind: str) -> Dict[str, Any]:
+    parts = text.split(":", 2 if kind == "store" else 1)
+    if len(parts) != (3 if kind == "store" else 2) or not _SLOT_NAME.match(parts[0]) or not parts[-1].strip():
+        raise AdaptationError("--%s takes %s" % (kind, "NAME:PATH:PURPOSE" if kind == "store" else "NAME:PURPOSE"))
+    slot = {"name": parts[0], "kind": kind, "purpose": parts[-1].strip()}
+    if kind == "store":
+        slot["path"] = parts[1]
+    if _secrets.secret_value(slot["purpose"]):
+        raise AdaptationError("a slot is named, never filled: --%s %s holds a value shaped like a credential" % (kind, parts[0]))
+    return slot
+
+
+def source_manifest(include: Sequence[str], description: Optional[str] = None, secrets: Sequence[str] = (),
+                    stores: Sequence[str] = (), service: bool = False, provider: bool = True) -> Dict[str, Any]:
+    """A fabric-source/1 manifest: include as given (sorted, default deny), the kit's slots, the slots named."""
+    manifest: Dict[str, Any] = {"format": "fabric-source/1"}
+    if description:
+        manifest["description"] = description
+    manifest["include"] = sorted(dict.fromkeys(include))
+    slots = [_parse_slot(t, "secret") for t in secrets] + [_parse_slot(t, "store") for t in stores]
+    slots += ([dict(PUBLISHER_SLOT)] if provider else []) + [dict(PLACEMENT_SLOT)]
+    slots += [dict(s) for s in SERVICE_SLOTS] if service else []
+    names = [s["name"] for s in slots]
+    if len(set(names)) != len(names):
+        raise AdaptationError("a slot is named twice")
+    manifest["slots"] = slots
+    return manifest
+
+
+def _top_level(root: Path) -> List[str]:
+    """The project's top-level entries as include paths: what Git would commit, else what a walk finds; a folder with
+    a trailing /. Instance data by its name is left out."""
+    names: List[str] = []
+    try:
+        listed = subprocess.run(["git", "-C", str(root), "ls-files", "-z", "--cached", "--others", "--exclude-standard"],
+                                capture_output=True, timeout=60)
+        if listed.returncode == 0:
+            names = [os.fsdecode(n) for n in listed.stdout.split(b"\0") if n]
+    except (OSError, subprocess.SubprocessError):
+        names = []
+    if not names:
+        names = [_relative(path, root) for path in _files(root)]
+    tops = []
+    for name in names:
+        head, _, rest = name.partition("/")
+        if not _NOT_SOURCE.fullmatch(head):
+            tops.append(head + "/" if rest else head)
+    return sorted(dict.fromkeys(tops))
+
+
+def write_source_manifest(root: Path, args: argparse.Namespace) -> Dict[str, Any]:
+    """`source`: lay down fabric.source.json from the project's top-level entries. An existing one is the owner's and
+    is kept unless --force; --dry-run writes nothing."""
+    if not root.is_dir():
+        raise AdaptationError("project path is not a directory: %s" % root)
+    provider = (root / "fabric-agent.json").is_file()
+    manifest = source_manifest(_top_level(root), args.description, args.secret, args.store, args.service, provider)
+    target = root / SOURCE_FILE
+    exists = os.path.lexists(str(target))
+    result = {"project": str(root.resolve()), "manifest": manifest, "exists": exists}
+    if args.dry_run:
+        result["dryRun"] = True
+        return result
+    if exists and not args.force:
+        raise AdaptationError("%s exists: it is the owner's; --dry-run shows the proposal, --force replaces it" % SOURCE_FILE)
+    target.write_text(_json_text(manifest), encoding="utf-8")
+    result["written"] = SOURCE_FILE
+    result["next"] = ("Review include (default deny), name every key and store as a slot, then run "
+                      "fabric_source_check.py check on the project (exit 0).")
+    return result
+# #endregion
+
+
 def _load_json(path: Path, errors: List[str]) -> Optional[Any]:
     try:
         return json.loads(path.read_text(encoding="utf-8"))
@@ -834,6 +926,17 @@ def build_parser() -> argparse.ArgumentParser:
     scaffold.add_argument("--dry-run", action="store_true", help="print the planned writes and a unified diff of each existing path; write nothing")
     scaffold.add_argument("--json", action="store_true")
 
+    source = sub.add_parser("source", help="lay down fabric.source.json, the agent's source manifest (DEC-0149)")
+    source.add_argument("project", type=Path)
+    source.add_argument("--description", help="what the agent is, in plain words")
+    source.add_argument("--secret", action="append", default=[], metavar="NAME:PURPOSE", help="a key the agent reads by name; repeat")
+    source.add_argument("--store", action="append", default=[], metavar="NAME:PATH:PURPOSE",
+                        help="a data store relative to the data folder (it becomes the package's state[]); repeat")
+    source.add_argument("--service", action="store_true", help="a kit service: its supervisor label and port are slots")
+    source.add_argument("--force", action="store_true", help="replace an existing fabric.source.json")
+    source.add_argument("--dry-run", action="store_true", help="print the proposal; write nothing")
+    source.add_argument("--json", action="store_true")
+
     check = sub.add_parser("check", help="check generated structure and optional pinned schema")
     check.add_argument("project", type=Path)
     check.add_argument("--contract", type=Path)
@@ -848,6 +951,8 @@ def main(argv: Optional[Sequence[str]] = None) -> int:
             result = inspect_project(args.project)
         elif args.command == "scaffold":
             result = scaffold_project(args.project, args)
+        elif args.command == "source":
+            result = write_source_manifest(args.project, args)
         else:
             result = check_project(args.project, args.contract)
         if result.get("dryRun") and not args.json:

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

@@ -28,8 +28,14 @@ CREDENTIAL_PAIRS = {
     'session': {'token', 'id'},
     'code': {'login', 'auth', 'access', 'session'}}
 JWT_SHAPE = re.compile(r'eyJ[A-Za-z0-9_-]{2,}\.[A-Za-z0-9_-]{2,}\.[A-Za-z0-9_-]*')
-SECRET_VALUE = re.compile(r'(^bearer\s.+|sk-[A-Za-z0-9_-]{16,}|gh[pousr]_[A-Za-z0-9]{20,}|xox[abposr]-[A-Za-z0-9-]{10,}'
-                          r'|AKIA[0-9A-Z]{16}|glpat-[A-Za-z0-9_-]{20,})', re.I | re.S)
+# The contract's SECRET_VALUE at the pin (DEC-0151): `Bearer ` at a value's start in any case, or a provider key with its
+# prefix in its canonical case after a boundary (the start, a character that is no ASCII letter or digit, or an escape);
+# an `sk-` key holds a digit and an upper-case letter with 16 or more characters, or a digit with 32 or more.
+SECRET_VALUE = re.compile(r'(^[Bb][Ee][Aa][Rr][Ee][Rr]\s.+|(?:^|[^A-Za-z0-9]|%[0-9A-Fa-f]{2}|\\[nrt"\']|\\u[0-9A-Fa-f]{4}'
+                          r'|\\x[0-9A-Fa-f]{2}|\\[bfv0ae]|\\[0-7]{1,3}|%25[0-9A-Fa-f]{2}|\x1b\[[0-9;:]*m'
+                          r'|(?:\\u001[bB]|\\x1[bB]|\\e|\\033|\\33)\[[0-9;:]*m)'
+                          r'(?:sk-(?=[A-Za-z0-9_-]{0,255}?[0-9])(?:(?=[A-Za-z0-9_-]{0,255}?[A-Z])[A-Za-z0-9_-]{16,}|[A-Za-z0-9_-]{32,})'
+                          r'|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,}))', re.S)
 LONG_RUN = re.compile(r'[A-Za-z0-9+/=_-]{40,}')
 
 
@@ -115,6 +121,11 @@ def check(data):
     require(all(isinstance(v, str) and 0 < len(v) <= 200 for v in (target, viewer)), 'missing_device')
     fallback = data.get('fallback', 'if_absent')
     require(fallback in ('if_absent', 'never'), 'invalid_fallback')
+    # DEC-0154 PL-3 and HA-2 (FAA-251): who listens on http_url's port, as the host read it from the socket table
+    # (fabric_peer_owner's kinds, or check_service.py's foreign-user). A browser opens a raw loopback address only
+    # after that listener is this OS account's; absent, it is unknown.
+    owner = data.get('listener_owner', 'unknown')
+    require(owner in ('this-account', 'another-account', 'system', 'unknown', 'none', 'foreign-user'), 'invalid_listener_owner')
     kind = action.get('kind')
     if kind == 'remote_open':
         require(set(action) <= {'kind', 'device_id', 'service', 'path'}, 'unexpected_action_field')
@@ -128,17 +139,26 @@ def check(data):
         require(set(action) == {'kind', 'url'} and action.get('url') == http, 'not_resolved_http_url')
         require(viewer == target, 'wrong_viewer_device')
         require(state == 'not_installed' and fallback == 'if_absent', 'browser_fallback_forbidden')
+        require(owner == 'this-account', 'listener_not_this_account')
     else:
         raise ValueError('unsupported_dashboard_action')
     return {'ok': True, 'kind': kind}
 
 
+def read_input(limit=65536):
+    # The handoff's bytes, decoded as UTF-8 with a byte order mark dropped: Windows before Python 3.15 decodes a text
+    # stdin with its code page, which misreads a Cyrillic handoff (FAA-210). A stream without bytes is read as text.
+    stream = getattr(sys.stdin, 'buffer', None)
+    raw = stream.read(limit + 1) if stream is not None else sys.stdin.read(limit + 1)
+    require(len(raw) <= limit, 'input_too_large')
+    return raw.decode('utf-8-sig') if isinstance(raw, bytes) else raw.lstrip('\ufeff')
+
+
 def main():
     try:
-        raw = sys.stdin.read(65537)
-        require(len(raw) <= 65536, 'input_too_large')
-        result = check(json.loads(raw))
-    except (ValueError, TypeError, KeyError, AttributeError):
+        result = check(json.loads(read_input()))
+    # RecursionError: Python 3.9 to 3.13 raise it on a deeply nested document under the cap
+    except (ValueError, TypeError, KeyError, AttributeError, RecursionError):
         # Fixed reasons only: never echo a submitted URL, token or JSON blob.
         result = {'ok': False, 'reason': 'dashboard_handoff_refused'}
     print(json.dumps(result))

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

@@ -17,6 +17,7 @@ itself takes an option of the same name. --env is for a stdio server only and is
 
 Normative source: fabric-agent-contract docs/specification/provider.md (DEC-0016, rulings DEC-0017).
 """
+# Example URLs write their scheme in angle brackets: read `<https>` as `https` (FAA-212).
 
 # #region provider-writer — docs: plugins/fabric-agent-adapter/skills/adapting-projects-to-fabric/references/provider-entry.md#the-writer
 
@@ -292,6 +293,13 @@ def _now() -> str:
     return dt.datetime.now(dt.timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
 
 
+
+def entry_stem(path: str) -> str:
+    """CT-193 (FAC-SEM-014): the stem registry-rules.ts reads, `file.replace(/^.*[\\/]/, "").replace(/\\.json$/, "")`,
+    with ECMAScript's `.` (no line break: \\n, \\r, U+2028, U+2029) and `$` (the string's end) (FAA-189)."""
+    return re.sub(r"\.json\Z", "", re.sub(r"\A[^\n\r\u2028\u2029]*[\\/]", "", path, count=1))
+
+
 def main(argv: Optional[List[str]] = None) -> int:
     parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     sub = parser.add_subparsers(dest="command", required=True)
@@ -327,7 +335,7 @@ def main(argv: Optional[List[str]] = None) -> int:
             entry = json.loads(args.path.read_text(encoding="utf-8"))
             problems = validate_provider_entry(entry)
             # CT-193 (FAC-SEM-014): the stem is what follows the last / or \ and loses .json, on every platform.
-            stem = re.sub(r"\.json\Z", "", re.sub(r"^.*[\\/]", "", str(args.path), flags=re.S))
+            stem = entry_stem(str(args.path))
             if isinstance(entry, dict) and entry.get("id") != stem:
                 problems.append("the file name %s is not <id>.json for %s (FAC-SEM-014)" % (args.path.name, entry.get("id")))
             if not problems:

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

@@ -6,6 +6,7 @@ only. The dashboard kit's fabric-button.js carries its own copy of the name and
 
 It reads as the contract's ECMAScript does (FAA-136): ECMAScript's whitespace (Python's `\\s` also takes U+0085 and
 U+001C to U+001F, and not U+FEFF), `.` stopping at every line terminator, ASCII case folding, an ASCII word boundary."""
+# Example URLs write their scheme in angle brackets: read `<https>` as `https` (FAA-212).
 
 from __future__ import annotations
 
@@ -29,8 +30,20 @@ CREDENTIAL_PAIRS: Dict[str, tuple] = {
 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
 JWT_SHAPE = re.compile(r"eyJ[A-Za-z0-9_-]{2,}\.[A-Za-z0-9_-]{2,}\.[A-Za-z0-9_-]*")
-SECRET_VALUE = re.compile(r"(^bearer[%s]%s+|sk-[A-Za-z0-9_-]{16,}|gh[pousr]_[A-Za-z0-9]{20,}|xox[abposr]-[A-Za-z0-9-]{10,}"
-                          r"|AKIA[0-9A-Z]{16}|glpat-[A-Za-z0-9_-]{20,})" % (JS_SPACE, _NOT_LINE_END), re.IGNORECASE | re.ASCII)
+#: Where a provider key's prefix may start (DEC-0151): the start of a value, a character that is no ASCII letter or
+#: digit, or an escape (a percent-escape, single or double, a backslash escape, an octal, `\\x` with two hex digits,
+#: `\\u` with four, an ESC colour sequence, raw or escaped). A consuming group, as the contract writes it.
+_KEY_BOUNDARY = (r"(?:^|[^A-Za-z0-9]|%[0-9A-Fa-f]{2}|\\[nrt\"']|\\u[0-9A-Fa-f]{4}|\\x[0-9A-Fa-f]{2}|\\[bfv0ae]|\\[0-7]{1,3}"
+                 r"|%25[0-9A-Fa-f]{2}|\x1b\[[0-9;:]*m|(?:\\u001[bB]|\\x1[bB]|\\e|\\033|\\33)\[[0-9;:]*m)")
+#: The provider keys' shapes, prefixes in their canonical case only (DEC-0151 item 7: `SK-` or `GHP_` is no key). An
+#: `sk-` key holds, within 256 characters, a digit and an upper-case letter with 16 or more characters, or a digit with
+#: 32 or more; the look-aheads are bounded to 255 characters and lazy, so a long run of prefixes reads in linear time.
+_PROVIDER_KEYS = (r"(?:sk-(?=[A-Za-z0-9_-]{0,255}?[0-9])(?:(?=[A-Za-z0-9_-]{0,255}?[A-Z])[A-Za-z0-9_-]{16,}|[A-Za-z0-9_-]{32,})"
+                  r"|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,})")
+#: 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 + ")")
 _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,
                             re.IGNORECASE | re.ASCII)
@@ -142,7 +155,7 @@ def _percent_encode(text: str, also: str) -> str:
     return "".join(out)
 
 
-def _url_parts(value: str) -> Tuple[str, str, str]:
+def url_parts(value: str) -> Tuple[str, str, str]:
     """The password, query and fragment of an absolute URL as WHATWG URL parsing splits them, read by hand: urlsplit
     refuses a `[` or `]` outside an IPv6 host (`<https>://u:p[w@h/`), where `new URL` reads the password (0.56.0 unit
     r7). The fragment starts at the first `#`, the query at the first `?` before it. A special scheme's authority starts
@@ -166,6 +179,9 @@ def _url_parts(value: str) -> Tuple[str, str, str]:
             _percent_encode(fragment, "`"))
 
 
+_url_parts = url_parts  # the name before FAA-250, kept for code that reached it
+
+
 def secret_url(value: str) -> bool:
     """Whether a URL an MCP entry or a launch names carries a credential (LC-21): anything secret_argument finds, a
     password in its user information, or a query or fragment parameter whose name can only carry a credential and has
@@ -177,7 +193,7 @@ def secret_url(value: str) -> bool:
     value = re.sub(r"[\t\n\r]", "", value.strip(_C0_OR_SPACE))
     if not _SCHEME.match(value):
         return False  # not an absolute URL (WHATWG URL parsing refuses it)
-    password, query, fragment = _url_parts(value)
+    password, query, fragment = url_parts(value)
     if password:
         return True
     for part in (query, fragment):
@@ -190,7 +206,10 @@ def secret_url(value: str) -> bool:
 _REPOSITORY_URI = re.compile(r"\A([A-Za-z][A-Za-z0-9+.-]*:(?://[^/?#]*)?)([^?#]*)(.*)\Z", re.S)
 _REPOSITORY_NAME = re.compile(r"(?:[a-z0-9._-]+|[A-Za-z._-]+)\Z")  # lower case, or letters with no digit (readings 8)
 _REPOSITORY_AUTHORITY = re.compile(r"[A-Za-z][A-Za-z0-9+.-]*://")
-_KEY_AT_A_WORD = re.compile(r"(?:\A|(?<=[._-]))(?:%s)" % SECRET_VALUE.pattern, re.IGNORECASE | re.ASCII)
+#: A repository name's own key shapes, boundary-free and case-sensitive (DEC-0151): SECRET_VALUE takes a consuming
+#: 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)
 
 

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

@@ -44,7 +44,14 @@ shorter than three characters ignored, matched without regard to case. A list in
 is refused: it would travel with the source. The summary says whether Git chose the files or every file was read.
 Under a locale whose file-system encoding is not UTF-8 the check restarts itself in Python's UTF-8 mode, so a name,
 an argument and a file are read in one encoding. Standard library only.
+
+Under a source manifest (DEC-0149, FAA-261): when ROOT holds `fabric.source.json`, the manifest decides what is source
+and the contract's tree check reads it (fabric_source_tree.py, held to the contract's vectors): blocking findings exit
+1, warnings alone (`email`, `link-outside`, `no-license`, `unused-exclude`, `excluded-by-fold`) exit 0, a source file
+not read exits 2; each finding names its path, line and column, never the text found. `.fabric-source-ignore` and
+`--exclude` are not read there.
 """
+# Example URLs write their scheme in angle brackets: read `<https>` as `https` (FAA-212).
 
 # #region source-check — docs: plugins/fabric-agent-adapter/skills/creating-fabric-agents/references/source-and-instance.md#the-check
 
@@ -64,6 +71,28 @@ from urllib.parse import unquote
 from typing import Dict, Iterable, List, NoReturn, Optional, Set, Tuple
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+
+def _refuse_sibling(step: str, missing: BaseException) -> NoReturn:
+    """A sibling module that did not load: name it and exit 2, never a traceback and never exit 1 (a finding)."""
+    # the exception's own text is never printed: an OSError's carries a path, which may be under the owner's home
+    why = "a module beside this file refused to load"
+    try:
+        here, sibling = Path(__file__).resolve().parent, step + ".py"
+        file = getattr(missing, "filename", None) if isinstance(missing, OSError) else None
+        why = ("%s must sit beside this file" % sibling if not (here / sibling).is_file()
+               else "%s beside this file cannot be read" % sibling
+               if isinstance(file, (str, bytes)) and Path(os.fsdecode(file)).resolve() == here / sibling
+               else "%s beside this file is from another version: copy it with this one" % sibling
+               if isinstance(missing, (ImportError, SyntaxError))
+               else "%s beside this file refused to load (%s): copy the scripts folder whole, from one version"
+               % (sibling, type(missing).__name__))
+    except Exception:  # naming the cause must never be what fails
+        pass
+    sys.stderr.write("fabric_source_check.py: %s\n" % why)
+    sys.exit(2)
+
+
 _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
 try:
@@ -71,26 +100,13 @@ try:
     _STEP = "fabric_source_ignore"
     from fabric_source_ignore import (  # noqa: E402,F401 - how the ignore lines are read, beside this file
         IGNORE_FILE, CheckError, _as_bytes, _glob, _ignored, _line, _readable_glob, ignore_globs)
+    _STEP = "fabric_source_restart"
+    from fabric_source_restart import _interpreter, _interpreter_flags, _keep_console, _utf8_restart  # noqa: E402,F401
     _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)
 except Exception as _missing:  # a copy without its siblings, or mixed from two versions: a refusal, never exit 1
-    # the exception's own text is never printed: an OSError's carries a path, which may be under the owner's home
-    _why = "a module beside this file refused to load"
-    try:
-        _HERE, _sibling = Path(__file__).resolve().parent, _STEP + ".py"
-        _file = getattr(_missing, "filename", None) if isinstance(_missing, OSError) else None
-        _why = ("%s must sit beside this file" % _sibling if not (_HERE / _sibling).is_file()
-                else "%s beside this file cannot be read" % _sibling
-                if isinstance(_file, (str, bytes)) and Path(os.fsdecode(_file)).resolve() == _HERE / _sibling
-                else "%s beside this file is from another version: copy it with this one" % _sibling
-                if isinstance(_missing, (ImportError, SyntaxError))
-                else "%s beside this file refused to load (%s): copy the scripts folder whole, from one version"
-                % (_sibling, type(_missing).__name__))
-    except Exception:  # naming the cause must never be what fails
-        pass
-    sys.stderr.write("fabric_source_check.py: %s\n" % _why)
-    sys.exit(2)
+    _refuse_sibling(_STEP, _missing)
 finally:
     sys.dont_write_bytecode = _WROTE_BYTECODE
 
@@ -126,13 +142,16 @@ PRIVATE_KEY = re.compile(r"-----BEGIN (?:[A-Z0-9]+ )*PRIVATE KEY(?: BLOCK)?-----
 JWK_PRIVATE = re.compile(r"\\?[\"']d\\?[\"'][ \t]*:[ \t]*\\?[\"']([A-Za-z0-9_-]{43,})")  # JSON, escaped, Python
 #: Words a documented or synthetic credential carries (AWS's `...EXAMPLE`, `sk-test-not-a-key`); a random key does not.
 SYNTHETIC = ("example", "not-a-key", "notakey", "fake", "dummy", "placeholder", "redacted")
-# The detector's provider-key shapes without its first alternative, `^bearer\s.+`, which reads a whole header value: in
-# a file it would take prose that starts with the word and hide a key later on the same line. A bearer token is looked
-# for as `_BEARER_INSIDE` does: the word, then a run of 12 or more with a digit.
-_BEARER_FIRST = "(^bearer["
-if not _secrets.SECRET_VALUE.pattern.startswith(_BEARER_FIRST):  # not an assert: `python -O` would drop it
-    raise ImportError("fabric_secrets.SECRET_VALUE changed its first branch; update fabric_source_check.py with it")
-PROVIDER_KEY = re.compile("(" + _secrets.SECRET_VALUE.pattern.split("|", 1)[1], _secrets.SECRET_VALUE.flags)
+# 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.
+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) + ")",
+                              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).
 _JS_DOT = "[^\n\r\u2028\u2029]"
@@ -200,7 +219,7 @@ def _url_secret(url: str, depth: int = 0) -> bool:
     url = url.rstrip(".,;)]}")
     if not _secrets._SCHEME.match(url):
         return False
-    password, query, fragment = _secrets._url_parts(url)
+    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`)
     if len(password) >= 8 and re.search(r"[0-9]", password) and re.search(r"[A-Za-z]", password) and _real(unquote(password)):
         return True
@@ -215,7 +234,7 @@ def _url_secret(url: str, depth: int = 0) -> bool:
                 if not _real(value):
                     continue
                 if (_secrets.credential_name(name) and _secrets._long_secret(value)) or \
-                        _secrets.JWT_SHAPE.search(value) or _secrets.SECRET_VALUE.search(value):
+                        _secrets.JWT_SHAPE.search(value) or URL_SECRET_VALUE.search(value):
                     return True
     return False
 
@@ -398,13 +417,13 @@ def _instance_finding(text: str, entries: List[str]) -> Optional[str]:
 
 
 def _alternatives(pattern: "re.Pattern[str]") -> List[Tuple["re.Pattern[str]", ...]]:
-    """Each provider-key alternative of the contract's pattern as (its starts, its prefix, a run of its class, least
+    """Each provider-key alternative of this check's pattern as (its starts, its prefix, a run of its class, least
     length, open-ended, the whole alternative), so a key is read where its own class ends, not where another's does."""
     found = []
     for alt in pattern.pattern[1:-1].split("|"):
         part = re.fullmatch(r"(.+?)(\[[^\]]+\])\{(\d+)(,?)\}", alt)
         if part is None:  # not an assert: `python -O` would drop it
-            raise ImportError("fabric_secrets.SECRET_VALUE has a key shape this check cannot read: %s" % alt[:12])
+            raise ImportError("KEY_SHAPE_SOURCES has a key shape this check cannot read: %s" % alt[:12])
         prefix, cls, least, open_ended = part.groups()
         found.append((re.compile("(?=%s)" % prefix, pattern.flags), re.compile(prefix, pattern.flags),
                       re.compile(cls + "+", pattern.flags), int(least), bool(open_ended), re.compile(alt, pattern.flags)))
@@ -713,6 +732,15 @@ def check(root: Path, entries: List[str], globs: List[str], every_file: bool = F
         files, mode = _walk_files(root, unreadable, PACK_REFUSES), "walk"
     elif not files:  # not a checkout, Git refused it, or a folder Git ignores or holds nothing of: read what is there
         files, mode = _walk_files(root, unreadable, WALK_SKIP, dependencies), "walk"
+    if os.path.lexists(str(root / "fabric.source.json")):  # DEC-0149: the manifest decides (fabric_source_tree.py)
+        wrote, sys.dont_write_bytecode = sys.dont_write_bytecode, True  # a copy inside the tree adds no .pyc
+        try:
+            import fabric_source_tree  # noqa: E402 - beside this file; imported here, since it imports this one
+        except Exception as missing:  # the same named-sibling refusal as the imports at the top (exit 2)
+            _refuse_sibling("fabric_source_tree", missing)
+        finally:
+            sys.dont_write_bytecode = wrote
+        return fabric_source_tree.check_folder(root, files, mode, entries, unreadable, dependencies)
     findings: List[Dict[str, object]] = []
     read = 0
     skipped = {"binary": 0, "unreadable": len(unreadable), "excluded": 0, "nested": 0, "dependencies": len(dependencies)}
@@ -891,6 +919,8 @@ def run(argv: Optional[List[str]] = None) -> int:
     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))
@@ -925,55 +955,6 @@ def run(argv: Optional[List[str]] = None) -> int:
     return 0 if complete else 2
 
 
-def _utf8_restart(encoding: str, utf8_mode: int, executable: str, argv: List[str]) -> Optional[List[bytes]]:
-    """The command that restarts the check in Python's UTF-8 mode, or None when it needs none. Under a locale whose
-    file-system encoding is not UTF-8 (ISO-8859-1, KOI8-R, a C locale with UTF-8 mode off), a name, an argument and a
-    file's text would each be read in its own encoding; in UTF-8 mode all three are, and a byte that is not UTF-8 stays
-    that byte. Windows names are UTF-16 and need none. The arguments go back as the bytes they came in. An empty list:
-    a restart is needed and no interpreter is known (the caller exits 2 rather than read in two encodings)."""
-    if os.name == "nt" or utf8_mode or encoding.lower().replace("_", "-") in ("utf-8", "utf8"):
-        return None
-    if not executable:
-        return []
-    return [os.fsencode(executable), b"-X", b"utf8"] + [os.fsencode(a) for a in argv]
-
-
-def _interpreter() -> str:
-    """The running interpreter: Linux's `/proc/self/exe`, which no PATH or working folder can stand in for (Python 3.9
-    may take a `./python3` of the working folder as sys.executable), else sys.executable, which may be empty."""
-    try:
-        return os.readlink("/proc/self/exe")
-    except (OSError, AttributeError):
-        return sys.executable or ""
-
-
-def _interpreter_flags(flags: object, xoptions: Dict[str, object]) -> List[str]:
-    """The interpreter's own options, rebuilt where sys.orig_argv is missing (Python 3.9), so a restart keeps `-I`."""
-    out: List[str] = []
-    if getattr(flags, "isolated", 0):
-        out.append("-I")
-    else:
-        out += ["-E"] * bool(getattr(flags, "ignore_environment", 0)) + ["-s"] * bool(getattr(flags, "no_user_site", 0))
-    out += ["-S"] * bool(getattr(flags, "no_site", 0)) + ["-B"] * bool(getattr(flags, "dont_write_bytecode", 0))
-    if getattr(flags, "optimize", 0):
-        out.append("-" + "O" * int(getattr(flags, "optimize")))
-    for key, value in xoptions.items():
-        if key not in ("utf8", "fabric_console"):
-            out += ["-X", key if value is True else "%s=%s" % (key, value)]
-    return out
-
-
-def _keep_console(xoptions: Dict[str, object]) -> None:
-    """After a restart, write the console's own encoding again (the parent named it in `-X fabric_console=`)."""
-    console = xoptions.get("fabric_console")
-    if isinstance(console, str):
-        for stream in (sys.stdout, sys.stderr):
-            try:
-                stream.reconfigure(encoding=console, errors="backslashreplace")  # type: ignore[union-attr]
-            except (AttributeError, LookupError, ValueError):
-                pass
-
-
 if __name__ == "__main__":
     _keep_console(getattr(sys, "_xoptions", {}))
     _argv = (list(sys.orig_argv[1:]) if hasattr(sys, "orig_argv")