@passioncode-ai/passioncode 0.2.37 → 0.2.39

package/payload/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/check_service_rules.py

@@ -1,6 +1,7 @@
 """The probe's rules that read one thing and need no running service (FAA-65): a plist's marker and priority, the
-network guard's verdict, the board responder's fixture conversation, a session cookie's lifetime, a usage report, and
-whether two repository URLs name one repository. ``check_service.py`` runs them against a live service.
+network guard's verdict, the board responder's fixture conversation, a session cookie's lifetime, a usage report,
+whether two repository URLs name one repository, a service's actions declaration (DEC-0121) and whether its checkout
+opens its pages in a browser (FAA-118). ``check_service.py`` runs them against a live service.
 Standard library only, Python 3.9+."""
 from __future__ import annotations
 
@@ -17,6 +18,7 @@ from typing import Any, Dict, Iterable, List, Optional, Tuple
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 import fabric_service as fs  # noqa: E402 - beside this file
+import fabric_actions as fa  # noqa: E402 - beside this file (DEC-0121)
 
 
 def plist_problems(plist: dict, label: object, token: object = None) -> list:
@@ -291,3 +293,324 @@ def same_repository(a: str, b: str) -> bool:
         u = re.sub(r"^[^@/]+@", "", u)
         return re.sub(r"\.git$", "", u).rstrip("/")
     return bool(a and b) and norm(a) == norm(b)
+
+
+# actions (fabric-actions/0.1, DEC-0121, FAC-SEM-142) ----------------------------------------
+_ACTIONS_KEY_PATH = "/extensions/" + fa.ACTIONS_EXTENSION_KEY.replace("~", "~0").replace("/", "~1")
+
+
+def _actions_place(instance_path: str) -> str:
+    """A finding's place inside the declaration (`/actions/1/id`), or the declaration itself."""
+    inner = instance_path[len(_ACTIONS_KEY_PATH):] if instance_path.startswith(_ACTIONS_KEY_PATH) else instance_path
+    return inner or "extensions/actions/0.1"
+
+
+def well_known_actions_verdict(wk: Any) -> Tuple[str, str]:
+    """`well-known.actions`: a declared extensions/actions/0.1 is FAC-SEM-142's (the kit's actions_extension_rules, the
+    contract's reader): its schema's, each id once, humanStep exactly when gate is human, every tool in a present
+    surfaces.mcp.capabilities. No declaration is NOT_RUN: dashboard.actions-declared says what that means."""
+    view = fa.actions_view(wk)
+    if not view["declared"]:
+        return "NOT_RUN", "no extensions/actions/0.1 declaration (DEC-0121 AP-1)"
+    findings = fa.actions_extension_rules(wk)
+    if findings:
+        return "FAIL", "; ".join("FAC-SEM-142 %s: %s" % (_actions_place(f["instancePath"]), f["message"]) for f in findings[:5])
+    gates: Dict[str, int] = {}
+    for action in view["actions"]:
+        gates[action["gate"]] = gates.get(action["gate"], 0) + 1
+    return "PASS", "%d action(s) (%s), FAC-SEM-142 holds" % (
+        len(view["actions"]), ", ".join("%d %s" % (n, g) for g, n in sorted(gates.items())))
+
+
+def action_tools_verdict(wk: Any, tools: Optional[Dict[str, Any]], why_not: str = "tools/list was not read",
+                         no_surface: bool = False, remote: bool = False) -> Tuple[str, str]:
+    """`interop.action-tools`: every declared action's tool is served by tools/list, the live surface (FAC-SEM-142
+    checks only the list the document names). `tools` None means no listing was read; `why_not` says why. A local
+    service that declares actions and has no MCP surface fails: every action has a tool on its agent surface
+    (DEC-0121 AP-1), and a local service's is MCP. A remote agent's surface may be A2A or MCP behind a gateway (the
+    contract's surfaces table), so there it is NOT_RUN. This goes beyond FAC-SEM-142, which reads only a present list."""
+    view = fa.actions_view(wk)
+    if not view["declared"]:
+        return "NOT_RUN", "no extensions/actions/0.1 declaration"
+    if not view["valid"]:
+        return "NOT_RUN", "the actions declaration is not readable (well-known.actions): a reader treats it as not declared"
+    if no_surface and remote:
+        return "NOT_RUN", ("%d action(s) declared and no MCP surface: a remote agent's twin may be on A2A or behind a "
+                           "gateway, which this probe does not read" % len(view["actions"]))
+    if no_surface:
+        return "FAIL", ("%d action(s) declared but the service has no MCP surface: buttons without an agent twin "
+                        "(DEC-0121 AP-1)" % len(view["actions"]))
+    if tools is None:
+        return "NOT_RUN", why_not
+    missing = ["%s (%s)" % (a["tool"], a["id"]) for a in view["actions"] if a["tool"] not in tools]
+    if missing:
+        return "FAIL", ("tools/list does not serve %s: a button without an agent twin (DEC-0121 AP-1)" % ", ".join(missing))
+    return "PASS", "%d declared action(s), every tool served by tools/list" % len(view["actions"])
+
+
+def actions_declared_verdict(wk: Any) -> Tuple[str, str]:
+    """`dashboard.actions-declared` (decision D10): a dashboard whose declaration FAC-SEM-142 accepts passes, one it
+    finds (unreadable, a repeated id, a step that disagrees with the gate, a tool the surface does not list) fails,
+    and one with none is NOT_RUN, never FAIL: a read-only dashboard cannot declare an empty list
+    (minItems 1), so absence proves no page-only button. Fabric Dashboards reports it (CT-126)."""
+    surfaces = wk.get("surfaces") if isinstance(wk, dict) else None
+    if not (isinstance(surfaces, dict) and surfaces.get("dashboard")):
+        return "NOT_RUN", "no surfaces.dashboard"
+    view = fa.actions_view(wk)
+    if not view["declared"]:
+        return "NOT_RUN", ("a dashboard with no extensions/actions/0.1 declaration: a read-only dashboard declares none "
+                           "(the list needs minItems 1), so its absence proves no page-only button; a dashboard with a "
+                           "button declares it and its agent twin (DEC-0121 AP-1). Fabric Dashboards reports it (CT-126)")
+    if not view["valid"]:
+        return "FAIL", "the dashboard's actions declaration is not readable, so a host treats it as not declared (well-known.actions)"
+    findings = fa.actions_extension_rules(wk)
+    if findings:
+        return "FAIL", "the dashboard's actions declaration breaks FAC-SEM-142 in %d place(s) (well-known.actions)" % len(findings)
+    return "PASS", "the dashboard declares %d action(s) with their tools (DEC-0121 AP-1)" % len(view["actions"])
+
+
+# dashboard.opens-in-host (FAA-118; the operator rule of 2026-10-24; decision D13) ----------------------------------
+# A service's own pages open only through Fabric Dashboards: the `open_link` of the fabric-dashboards MCP `link` tool,
+# opened with the host's `open` and `fallback=never`; a browser only on a confirmed `not_installed` host. The rule reads
+# the service's checkout, tracked text files only (`git grep -I`, no untracked file, no binary), within a time budget,
+# and reports a line that opens a browser at the service's pages. The matcher, kept precise on purpose:
+#
+# 1. An opener (`_OPENERS`): macOS `open -a <browser>` / `open -b <browser bundle id>` / `open <http(s) URL>` /
+#    `open $<...url|link|origin|dashboard|page...>`; `xdg-open`, `gio open`, `sensible-browser`, `x-www-browser`,
+#    `wslview`; Windows `start [""] <URL>`, `explorer <URL>`, `url.dll,FileProtocolHandler`; Python
+#    `webbrowser.open|open_new|open_new_tab|get(`; Electron `openExternal(`; a process call whose argv starts with one
+#    of those programs (`subprocess.run(["open", ...])`, `spawn("xdg-open", ...)`); and in a JavaScript or TypeScript
+#    file that imports the npm package `open`, a call of the name it was bound to (`open(...)`, never `x.open(...)`).
+#    Python's builtin `open(` and a page's `window.open(` are files and tabs, never an opener.
+# 2. Aimed at the service's pages: in code, the opener's line or one of the 5 lines before it (where a URL is built)
+#    names a loopback host (127.0.0.1, localhost, [::1], 0.0.0.0), the service's port as a whole number, its origin's
+#    host, its dashboard path (when it is not just "/") or its login path; or the opener's line names an identifier
+#    built on "dashboard" (`dashboard_url`, `openDashboard`; never the host app's name "Fabric Dashboards"). In prose
+#    the aim is on the opener's own line. An opener with no such aim (a docs site, a report file) is not this rule's.
+# 3. In prose (Markdown and the like) only code counts: a fenced block, or an inline code span (`open -a Safari ...`);
+#    "then open `http://localhost:3000`" is a sentence for a person. A prose line that forbids it (never, not, avoid,
+#    instead of, ...) is not a finding either.
+# 4. Not a finding: the host's own route (`fabric-dashboards://`, the "Fabric Dashboards" app, `open_link`,
+#    `native_link` on the line); the allowed fallback (`not_installed` on the line or the 5 before, or the gate's
+#    `browser_link` on the line); a comment line in code; and test, spec and fixture files, which plant raw opens on
+#    purpose.
+_BROWSERS = (r"(?:Safari(?: Technology Preview)?|Google Chrome(?: Canary| Dev| Beta)?|Chrome|Chromium|"
+             r"Firefox(?: Developer Edition| Nightly)?|Arc|Dia|Brave Browser|Brave|Microsoft Edge|Opera|Vivaldi|Orion|Zen)")
+_BUNDLES = (r"(?:com\.apple\.Safari\w*|com\.google\.Chrome\w*|org\.chromium\.Chromium|org\.mozilla\.firefox\w*|"
+            r"company\.thebrowser\.\w+|com\.brave\.Browser\w*|com\.microsoft\.edgemac\w*|com\.operasoftware\.Opera\w*|"
+            r"com\.vivaldi\.Vivaldi|com\.kagi\.kagimacOS)")
+_PROGRAMS = r"(?:open|xdg-open|wslview|sensible-browser|x-www-browser|gio|start|explorer(?:\.exe)?)"
+#: Where a shell command starts: a line, a separator, `$(`, a Makefile's `@`, `then`, `do`, `else` or cmd's `/c`, or
+#: right after an opening quote or backtick (a string a process call runs). `playwright-cli open <url>` is that tool's
+#: own subcommand, and `--proxy "http://..." open` an argument after a closing quote.
+_CMD = r"(?:(?:^|[;&|({@]|\$\(|\bthen\b|\bdo\b|\belse\b|/[cC]\b)\s*|[`'\"])"
+_OPENERS = re.compile("|".join((
+    _CMD + r"open\s+(?:-[a-zA-Z]+\s+)*-a\s+[\"']?" + _BROWSERS + r"(?![\w-])",
+    _CMD + r"open\s+(?:-[a-zA-Z]+\s+)*-b\s+[\"']?" + _BUNDLES,
+    _CMD + r"open\s+(?:-[gnF]\s+)*[\"'`]?(?:https?://|\$\{?\w*(?i:url|link|origin|dashboard|page)\w*)",
+    r"(?<![\w.$/-])(?:xdg-open|gio\s+open|sensible-browser|x-www-browser|wslview)(?![\w-])",
+    _CMD + r"start\s+(?:\"\"\s+)?[\"']?https?://",
+    _CMD + r"explorer(?:\.exe)?\s+[\"']?https?://",
+    r"url\.dll,\s*FileProtocolHandler",
+    r"\bwebbrowser\.(?:open|open_new|open_new_tab|get)\(",  # a call, never "webbrowser.open (the default)" in prose
+    r"\bopenExternal\(",
+    r"(?:spawn|spawnSync|execFile|execFileSync|exec|execSync|Popen|run|call|check_call|check_output)\s*\(\s*\[?\s*"
+    r"[\"'`]" + _PROGRAMS + r"[\"'`]\s*[,)\]]",
+)))
+_OPEN_PACKAGE = re.compile(r"""import\s+(\w+)\s+from\s+["']open["']|(?:const|let|var)\s+(\w+)\s*=\s*require\(\s*["']open["']\s*\)""")
+_JS_FILES = (".js", ".mjs", ".cjs", ".jsx", ".ts", ".mts", ".cts", ".tsx")
+_PROSE_FILES = (".md", ".markdown", ".mdx", ".rst", ".txt", ".adoc", ".org")
+_LOOPBACK = re.compile(r"(?:127\.0\.0\.1|\blocalhost\b|\[::1\]|0\.0\.0\.0)(?::(\d{1,5}))?")
+_HOST_ROUTE = re.compile(r"fabric-dashboards://|Fabric Dashboards|\b(?:open_link|openLink|native_link|nativeLink)\b")
+_FALLBACK = re.compile(r"\bnot[_-]installed\b|\bnotInstalled\b|\bNOT_INSTALLED\b")
+_GATE_LINK = re.compile(r"\b(?:browser_link|browserLink)\b")
+_NEGATION = re.compile(r"(?i)\b(?:never|not|don't|doesn't|avoid|instead of|forbidden|refused?|wrong|no longer|nonconformant)\b")
+_COMMENT = re.compile(r"\s*(?:#(?!!)|//|/\*|\*|<!--|REM\s|::)")
+_TEST_PATH = re.compile(r"(?:^|/)(?:tests?|__tests__|specs?|fixtures|testdata|e2e)/|(?:^|/)(?:test_[^/]*\.py|[^/]*_test\.\w+|"
+                        r"[^/]*\.(?:test|spec)\.\w+|conftest\.py)\Z")
+_WINDOW = 5  # lines before an opener that may hold its aim or the not_installed branch
+OPENS_IN_HOST_BUDGET = 3.0  # seconds for git and reading, as the session-start notice budgets its own git calls
+_MAX_CANDIDATES = 2000
+_MAX_FILE_BYTES = 1 << 20
+_COARSE = (r"open[[:space:]]+-[ab][[:space:]]|open[[:space:]]+[\"'`]?(https?://|\$)|xdg-open|gio[[:space:]]+open|"
+           r"sensible-browser|x-www-browser|wslview|start[[:space:]]+(\"\"[[:space:]]+)?[\"']?https?://|"
+           r"explorer(\.exe)?[[:space:]]+[\"']?https?://|FileProtocolHandler|webbrowser\.|openExternal|"
+           r"[\"'`](open|xdg-open|wslview|start|explorer)[\"'`]")
+
+
+def _aims(lines: List[str], port: int, host: str, dashboard_path: str) -> bool:
+    text = "\n".join(lines)
+    if "/fabric/v1/login" in text:
+        return True
+    # A loopback address is this service's only with its port or with none: another port is another local tool.
+    if any(m.group(1) is None or not port or int(m.group(1)) == port for m in _LOOPBACK.finditer(text)):
+        return True
+    if port and re.search(r"(?<!\d)%d(?!\d)" % port, text):
+        return True
+    if host and host in text:
+        return True
+    return bool(dashboard_path and dashboard_path != "/" and re.search(re.escape(dashboard_path) + r"(?![\w-])", text))
+
+
+#: Text before an opener that makes it a message for a person: `echo "... open http://..."`, print, a log call.
+_MESSAGE = re.compile(r"\b(?:echo|printf|print|puts|say)\b|\bconsole\.\w+\s*\(|\blog(?:ger)?\.\w+\s*\(|\blog\s*\(")
+_IDENTIFIER = re.compile(r"[A-Za-z_][A-Za-z0-9_]*")
+_FENCE = re.compile(r"\s*(?:```|~~~)")
+
+
+def _names_dashboard(line: str) -> bool:
+    """An identifier built on "dashboard" (dashboard_url, openDashboard), never the word alone or the host's name."""
+    return any("dashboard" in word.lower() and word.lower() not in ("dashboard", "dashboards")
+               for word in _IDENTIFIER.findall(line.split("://", 1)[0]))
+
+
+def _prose_code(lines: List[str]) -> List[str]:
+    """Each line of a prose file reduced to its code: whole inside a fenced block, else its inline code spans."""
+    out, fenced = [], False
+    for line in lines:
+        if _FENCE.match(line):
+            fenced = not fenced
+            out.append("")
+        elif fenced:
+            out.append(line)
+        else:
+            out.append(" ; ".join(re.findall(r"`([^`]+)`", line)))  # each span its own command
+    return out
+
+
+def opener_findings(path: str, text: str, port: int, origin: Optional[str], dashboard_path: Optional[str]) -> List[Tuple[int, str]]:
+    """The lines of one file (repository-relative `path`, its `text`) that open a browser at the service's pages, as
+    (line number, line); the matcher is described above. Never raises on what it reads."""
+    path = (path or "").replace("\\", "/")
+    if not isinstance(text, str) or _TEST_PATH.search(path):
+        return []
+    prose = path.lower().endswith(_PROSE_FILES)
+    calls = None
+    if path.lower().endswith(_JS_FILES):
+        names = [a or b for a, b in _OPEN_PACKAGE.findall(text)]
+        if names:
+            calls = re.compile(r"(?<![\w.$])(?:%s)\s*\(" % "|".join(re.escape(n) for n in names))
+    host = ""
+    if isinstance(origin, str) and "://" in origin:
+        host = origin.split("://", 1)[1].split("/", 1)[0].rsplit("@", 1)[-1]
+        if _LOOPBACK.fullmatch(host.rsplit(":", 1)[0]):
+            host = ""  # a loopback origin is covered by the loopback hosts and the port
+    original = text.splitlines()
+    lines = _prose_code(original) if prose else original
+    out: List[Tuple[int, str]] = []
+    for index, line in enumerate(lines):
+        match = _OPENERS.search(line) or (calls.search(line) if calls is not None and not _OPEN_PACKAGE.search(line) else None)
+        if match is None or _MESSAGE.search(line[:match.start()]):
+            continue
+        if _HOST_ROUTE.search(line) or _GATE_LINK.search(line):
+            continue
+        if (prose and _NEGATION.search(original[index])) or _COMMENT.match(line):
+            continue
+        window = lines[max(0, index - _WINDOW):index + 1]
+        if any(_FALLBACK.search(w) for w in window):
+            continue
+        aim = [line] if prose else window
+        if _aims(aim, port, host, str(dashboard_path or "")) or _names_dashboard(line):
+            out.append((index + 1, original[index].strip()))
+    return out
+
+
+def opens_in_host_verdict(repo: Path, port: int, origin: Optional[str], dashboard_path: Optional[str],
+                          budget: float = OPENS_IN_HOST_BUDGET) -> Tuple[str, str]:
+    """`dashboard.opens-in-host` over one checkout: FAIL with the places a tracked text file opens a browser at the
+    service's pages, PASS when none does, NOT_RUN when the checkout or git cannot be read or the budget runs out."""
+    until = time.monotonic() + max(0.0, budget)
+    if not shutil.which("git"):
+        return "NOT_RUN", "git is not installed"
+
+    def left() -> float:
+        return until - time.monotonic()
+
+    if left() <= 0:
+        return "NOT_RUN", "the %.1f s budget ran out before the checkout was read" % budget
+    try:
+        top = subprocess.run(["git", "-C", str(repo), "rev-parse", "--show-toplevel"], capture_output=True, text=True,
+                             timeout=max(0.05, left()))
+        if top.returncode != 0 or not top.stdout.strip():
+            return "NOT_RUN", "%s is not a Git checkout" % repo
+        root = Path(top.stdout.strip())
+        if left() <= 0:
+            return "NOT_RUN", "the %.1f s budget ran out before the checkout was read" % budget
+        listed = subprocess.run(["git", "-C", str(root), "grep", "-I", "-l", "-z", "-E", _COARSE], capture_output=True,
+                                timeout=max(0.05, left()))
+    except subprocess.TimeoutExpired:
+        return "NOT_RUN", "the %.1f s budget ran out while git read %s" % (budget, repo)
+    except OSError as exc:
+        return "NOT_RUN", "git could not read %s: %s" % (repo, exc)
+    if listed.returncode not in (0, 1):  # 1: nothing matched
+        return "NOT_RUN", "git grep could not read %s" % root
+    candidates = [p for p in listed.stdout.decode("utf-8", "surrogateescape").split("\0") if p]
+    if len(candidates) > _MAX_CANDIDATES:
+        return "NOT_RUN", "%d candidate files in %s, more than the %d this rule reads" % (len(candidates), root, _MAX_CANDIDATES)
+    found: List[str] = []
+    for name in candidates:
+        if left() <= 0:
+            return "NOT_RUN", "the %.1f s budget ran out after reading part of %s" % (budget, root)
+        try:
+            with open(root / name, "rb") as handle:
+                text = handle.read(_MAX_FILE_BYTES).decode("utf-8", "replace")
+        except OSError:
+            continue
+        found += ["%s:%d %s" % (name, line, snippet[:100]) for line, snippet in opener_findings(name, text, port, origin, dashboard_path)]
+    if found:
+        return "FAIL", ("%s. Open the service's pages through Fabric Dashboards: the open_link of the fabric-dashboards MCP "
+                        "link tool, opened with fallback=never; a browser only on a confirmed not_installed host "
+                        "(operator rule of 2026-10-24)" % "; ".join(found[:5] + (["and %d more" % (len(found) - 5)] if len(found) > 5 else [])))
+    return "PASS", ("%d tracked text file(s) in %s name a possible opener; none opens a browser at the service's pages: "
+                    "they open through Fabric Dashboards" % (len(candidates), root))
+
+
+def _git_out(cwd: Path, *args: str) -> Optional[str]:
+    try:
+        done = subprocess.run(["git", "-C", str(cwd)] + list(args), capture_output=True, text=True, timeout=2.0)
+    except (OSError, subprocess.SubprocessError):
+        return None
+    return done.stdout.strip() if done.returncode == 0 and done.stdout.strip() else None
+
+
+def service_checkout(descriptor: Any, repo: Optional[str]) -> Tuple[Optional[Path], str]:
+    """The service's checkout: `repo` (the probe's --repo) when given, else the checkout holding one of the
+    descriptor's paths (its commands, its fabricManifest, its launchd job's program and working directory) whose origin
+    is the descriptor's `source.repository`. (None, why) when there is none."""
+    if repo:
+        top = _git_out(Path(repo).expanduser(), "rev-parse", "--show-toplevel")
+        return (Path(top), "--repo") if top else (None, "--repo %s is not a Git checkout" % repo)
+    d = descriptor if isinstance(descriptor, dict) else {}
+    own = d.get("source")
+    source = own.get("repository") if isinstance(own, dict) else None
+    if not isinstance(source, str) or not source:
+        return None, "the descriptor names no source.repository to find the service's checkout by; pass --repo"
+    places: List[str] = []
+    commands = d.get("commands")
+    for argv in (commands.values() if isinstance(commands, dict) else []):
+        places += [a for a in argv if isinstance(a, str)] if isinstance(argv, list) else []
+    if isinstance(d.get("fabricManifest"), str):
+        places.append(d["fabricManifest"])
+    life = d.get("lifecycle") if isinstance(d.get("lifecycle"), dict) else {}
+    if isinstance(life.get("plist"), str):
+        try:
+            import plistlib
+            plist = plistlib.loads(Path(life["plist"]).expanduser().read_bytes())
+            places += [a for a in (plist.get("ProgramArguments") or []) if isinstance(a, str)]
+            places += [plist["WorkingDirectory"]] if isinstance(plist.get("WorkingDirectory"), str) else []
+        except (OSError, ValueError, AttributeError, TypeError, plistlib.InvalidFileException):
+            pass
+    seen = set()
+    for place in places:
+        if not (place.startswith(("/", "~")) or re.match(r"[A-Za-z]:[\\/]", place)):
+            continue
+        start = Path(os.path.expanduser(place))
+        while not start.is_dir() and start != start.parent:
+            start = start.parent
+        top = _git_out(start, "rev-parse", "--show-toplevel")
+        if not top or top in seen:
+            continue
+        seen.add(top)
+        if same_repository(_git_out(Path(top), "remote", "get-url", "origin") or "", source):
+            return Path(top), "the checkout of %s that holds %s" % (source, place)
+    return None, "no checkout of %s holds the descriptor's commands, manifest or launchd job; pass --repo" % source

package/payload/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/dashboard_kit.py

@@ -292,7 +292,8 @@ def services_of(repo: Path, directory: Optional[Path] = None, until: Optional[fl
             d = json.loads(path.read_text(encoding="utf-8"))
         except (OSError, ValueError):
             continue
-        source = str(((d.get("source") or {}) if isinstance(d, dict) else {}).get("repository") or "")
+        own = d.get("source") if isinstance(d, dict) else None
+        source = str(own.get("repository") or "") if isinstance(own, dict) else ""
         if same_repository(source, origin):
             found.append("%s.%s" % (d.get("id"), d.get("instance", "default")))
     return found

package/payload/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric-actions.mjs

@@ -0,0 +1,246 @@
+// Every action a person has, its agent tool and who decides it: fabric-actions/0.1, the extension keyed
+// extensions/actions/0.1 (DEC-0121, FAC-SEM-142). Part of the Node service kit (layer L3); the twin of fabric_actions.py.
+//
+// - actionDecision(inputs): whether a service takes a call of one declared action and as whose act it records it,
+//   exactly as the contract's actionDecision answers (AP-2, AP-4; DL-17, DL-18, DL-25). A `fault` is the service's
+//   own and is never sent to a caller.
+// - decisionShape(value): a decision as decision.schema.json reads it, `at` read strictly (the contract's strictTime).
+// - actionsView(wellKnown): the host reader of the declaration, as the contract's actionsView.
+// - actionsExtensionRules(wellKnown), actionRules(kind, value): FAC-SEM-142.
+// - actionsExtension(actions, { capabilities }): the `extensions` entry a service declares; it refuses a declaration
+//   FAC-SEM-142 would find, so a service never publishes one.
+// - operatorDecision({action, instruction, at, target}): the decision an agent relays in _meta.decision (AP-2, AP-3),
+//   refused when decision.schema.json would refuse it.
+// - actionCaller(tier, authenticated): the caller a service records (AP-2): the identity it authenticated, else
+//   local:T0 / local:T1 for a caller its local floor authenticated, never a name the call carries.
+//
+// The kit has no JSON Schema validator: the two shapes are written here from the schemas, lengths in code points and
+// patterns over the whole string, as the contract's validator reads them. Members are an object's own members (a JSON
+// text has no other kind; an inherited member is not read). Never throws on what it reads. Node 20+, no dependency.
+import { ServiceError } from './fabric-base.mjs';
+import { isObject, jsonEqual } from './fabric-jsvalue.mjs';
+import { formatRfc3339, parseRfc3339Ms } from './fabric-time.mjs';
+
+export const ACTIONS_EXTENSION_KEY = 'https://fabric.passioncode.ai/agent-contract/extensions/actions/0.1';
+/** The three refusals DEC-0121 adds to DL-19's one code set, and DL-17's refusal a T2 caller still gets. */
+export const OPERATOR_DECISION_REQUIRED = 'operator-decision-required';
+export const DECISION_INVALID = 'decision-invalid';
+export const HUMAN_STEP_REQUIRED = 'human-step-required';
+export const APPROVAL_REQUIRED = 'approval-required';
+export const GATES = Object.freeze(['none', 'relayed', 'human']);
+export const HUMAN_STEPS = Object.freeze(['sign-in', 'consent', 'payment', 'secret', 'spend-above-limit', 'passkey']);
+export const MAX_ACTIONS = 128;
+/** How far ahead of the service's clock a decision's `at` may be (the contract's CLOCK_SKEW_SECONDS). */
+export const CLOCK_SKEW_SECONDS = 60;
+/** How long after the operator decided a relayed decision still stands: approval/1's lifetime (DL-17, FAC-SEM-051). */
+export const DECISION_LIFETIME_SECONDS = 24 * 60 * 60;
+
+const REQUEST_KEY = /^[A-Za-z0-9_.-]{1,64}$/u; // interop-common.schema.json#/$defs/requestKey
+const CAPABILITY = /^[a-z][a-z0-9._-]{1,127}$/u; // common.schema.json#/$defs/capabilityName
+const SHA256 = /^sha256:[0-9a-f]{64}$/;
+const STEP_URL = /^(https:\/\/|\/)/;
+const ACTION_MEMBERS = new Set(['id', 'title', 'tool', 'gate', 'humanStep']);
+const DECISION_MEMBERS = new Set(['by', 'via', 'action', 'target', 'instruction', 'at']);
+const KEY_PATH = `/extensions/${ACTIONS_EXTENSION_KEY.replace(/~/g, '~0').replace(/\//g, '~1')}`;
+
+/** An own member that is not undefined, as the validator reads a member as present. */
+const has = (value, key) => Object.hasOwn(value, key) && value[key] !== undefined;
+/** An own member, or undefined. */
+const member = (value, key) => (isObject(value) && Object.hasOwn(value, key) ? value[key] : undefined);
+/** The number of code points, as the validator counts a string's length (a surrogate pair is one). */
+const codePoints = (value) => {
+  let count = 0;
+  for (const _ of value) count += 1;
+  return count;
+};
+const text = (value, low, high) => typeof value === 'string' && value.length <= high * 2 && codePoints(value) >= low && codePoints(value) <= high;
+const matches = (pattern, value, high) => typeof value === 'string' && value.length <= high && pattern.test(value);
+const nonEmpty = (value) => typeof value === 'string' && value.length > 0;
+const oneOf = (value, choices) => typeof value === 'string' && choices.includes(value);
+
+/** service-actions-extension.schema.json#/$defs/action: the errors at `at`, empty for a valid entry. */
+function actionErrors(value, at) {
+  if (!isObject(value)) return [`${at} type`];
+  const errors = Object.keys(value).filter((key) => !ACTION_MEMBERS.has(key)).map((key) => `${at}/${key} additionalProperties`);
+  for (const key of ['id', 'title', 'tool', 'gate']) if (!has(value, key)) errors.push(`${at} required ${key}`);
+  if (has(value, 'id') && !matches(REQUEST_KEY, value.id, 64)) errors.push(`${at}/id pattern`);
+  if (has(value, 'title') && !text(value.title, 1, 80)) errors.push(`${at}/title maxLength`);
+  if (has(value, 'tool') && !matches(CAPABILITY, value.tool, 128)) errors.push(`${at}/tool pattern`);
+  if (has(value, 'gate') && !oneOf(value.gate, GATES)) errors.push(`${at}/gate enum`);
+  if (has(value, 'humanStep') && !oneOf(value.humanStep, HUMAN_STEPS)) errors.push(`${at}/humanStep enum`);
+  return errors;
+}
+
+/** service-actions-extension.schema.json: the errors, empty for a valid declaration. */
+function extensionErrors(value) {
+  if (!isObject(value)) return ['/ type'];
+  const errors = Object.keys(value).filter((key) => key !== 'actions').map((key) => `/${key} additionalProperties`);
+  if (!has(value, 'actions')) return [...errors, '/ required actions'];
+  const { actions } = value;
+  if (!Array.isArray(actions)) return [...errors, '/actions type'];
+  if (actions.length < 1 || actions.length > MAX_ACTIONS) errors.push(`/actions ${actions.length ? 'maxItems' : 'minItems'}`);
+  actions.forEach((action, index) => errors.push(...actionErrors(action, `/actions/${index}`)));
+  return errors;
+}
+
+/** One valid actions[] entry whose humanStep is present exactly when gate is human. */
+export const readableAction = (action) => actionErrors(action, '').length === 0 && (action.gate === 'human') === has(action, 'humanStep');
+
+/**
+ * decision.schema.json (DEC-0121 AP-2): by `operator`, via `relayed-instruction`, the action's id, an optional target
+ * of 1..200, the operator's words of 1..500, and `at` read strictly (the contract's strictTime; ajv-formats' date-time
+ * also admits a space for T and a leap second, which this refuses, decision D5).
+ */
+export function decisionShape(value) {
+  if (!isObject(value) || Object.keys(value).some((key) => !DECISION_MEMBERS.has(key))) return false;
+  if (['by', 'via', 'action', 'instruction', 'at'].some((key) => !has(value, key))) return false;
+  return value.by === 'operator' && value.via === 'relayed-instruction' && matches(REQUEST_KEY, value.action, 64)
+    && (!has(value, 'target') || text(value.target, 1, 200)) && text(value.instruction, 1, 500)
+    && typeof value.at === 'string' && !Number.isNaN(parseRfc3339Ms(value.at));
+}
+
+const acceptedApproval = (approval) => isObject(approval) && member(approval, 'ok') === true && nonEmpty(member(approval, 'approver'));
+const refuse = (code) => ({ ok: false, code });
+
+/**
+ * Whether a service takes a call of one declared action, and as whose act it records it (DEC-0121 AP-2, AP-4; DL-17,
+ * DL-18, DL-25, DL-26), as the contract's actionDecision answers. `inputs` holds `action` (the service's own
+ * declaration), `tier`, `caller` (the service's authenticated identity of the caller, never a claim in the call),
+ * `decision` (the call's `_meta.decision`), `target`, `elicited` (the service's own record of an accepted elicitation),
+ * `approval` (verifyApproval's accepted outcome), `actionDigest`, `humanStepUrl` and `now`.
+ *
+ * none: the caller's own act. human: human-step-required with the step and its link, at every tier. relayed: an
+ * accepted approval is the approver's; a T2 caller without one gets approval-required with the digest; an accepted
+ * elicitation is the operator's; no decision is operator-decision-required; a decision that is not the schema's, is for
+ * another action or object, or whose `at` is more than 60 s ahead of `now` or more than 24 h behind it is
+ * decision-invalid; otherwise the operator's act, recorded with `caller`. `{fault}` (action-invalid, caller-missing,
+ * now-unreadable, digest-missing, url-missing) is the service's own and is never sent to a caller.
+ */
+export function actionDecision(inputs) {
+  const field = (key) => member(inputs, key);
+  const action = field('action');
+  if (!readableAction(action)) return { fault: 'action-invalid' };
+  if (action.gate === 'none') return { ok: true, recordAs: 'caller' };
+  if (action.gate === 'human') {
+    const url = field('humanStepUrl');
+    if (!nonEmpty(url) || !STEP_URL.test(url)) return { fault: 'url-missing' };
+    return { ok: false, code: HUMAN_STEP_REQUIRED, data: { humanStep: action.humanStep, url } };
+  }
+  const caller = field('caller');
+  if (!nonEmpty(caller)) return { fault: 'caller-missing' };
+  const approval = field('approval');
+  if (acceptedApproval(approval)) return { ok: true, recordAs: { by: approval.approver, via: 'approval', caller } };
+  const tier = field('tier');
+  if (tier !== 'T0' && tier !== 'T1') {
+    const digest = field('actionDigest');
+    if (typeof digest !== 'string' || !SHA256.test(digest)) return { fault: 'digest-missing' };
+    return { ok: false, code: APPROVAL_REQUIRED, data: { actionDigest: digest } };
+  }
+  if (field('elicited') === true) return { ok: true, recordAs: { by: 'operator', via: 'elicitation', caller } };
+  const clock = parseRfc3339Ms(field('now'));
+  if (Number.isNaN(clock)) return { fault: 'now-unreadable' };
+  const decision = field('decision');
+  if (decision === undefined) return refuse(OPERATOR_DECISION_REQUIRED);
+  if (!decisionShape(decision)) return refuse(DECISION_INVALID);
+  if (decision.action !== action.id || (has(decision, 'target') && decision.target !== field('target'))) return refuse(DECISION_INVALID);
+  const at = parseRfc3339Ms(decision.at);
+  if (at > clock + CLOCK_SKEW_SECONDS * 1000 || at < clock - DECISION_LIFETIME_SECONDS * 1000) return refuse(DECISION_INVALID);
+  return { ok: true, recordAs: { by: 'operator', via: 'relayed-instruction', caller } };
+}
+
+/**
+ * The host reader of extensions/actions/0.1 (DEC-0121 AP-1), as the contract's actionsView: {declared: false},
+ * {declared: true, valid: false, errors} or {declared: true, valid: true, actions}. Never throws.
+ */
+export function actionsView(wellKnown) {
+  const extensions = member(wellKnown, 'extensions');
+  if (!isObject(extensions) || !Object.hasOwn(extensions, ACTIONS_EXTENSION_KEY)) return { declared: false };
+  const value = extensions[ACTIONS_EXTENSION_KEY];
+  const errors = extensionErrors(value);
+  if (errors.length) return { declared: true, valid: false, errors };
+  return { declared: true, valid: true, actions: value.actions };
+}
+
+const finding = (instancePath, message) => ({ code: 'FAC-SEM-142', instancePath, message });
+
+/**
+ * FAC-SEM-142 on a well-known document that carries the actions key: a value that is not its schema's (one finding at
+ * the key); an id named twice; a humanStep present without gate human or absent with it; a tool that a present
+ * surfaces.mcp.capabilities does not list (a button without an agent twin, AP-1).
+ */
+export function actionsExtensionRules(wellKnown) {
+  const view = actionsView(wellKnown);
+  if (!view.declared) return [];
+  if (!view.valid) return [finding(KEY_PATH, `the actions declaration is invalid (${view.errors.join('; ')}); a reader treats it as not declared and reports it (DEC-0121)`)];
+  const capabilities = member(member(member(wellKnown, 'surfaces'), 'mcp'), 'capabilities');
+  const findings = [];
+  const seen = new Set();
+  view.actions.forEach((action, index) => {
+    const at = `${KEY_PATH}/actions/${index}`;
+    if (seen.has(action.id)) findings.push(finding(`${at}/id`, `action ${action.id} is declared twice`));
+    seen.add(action.id);
+    if ((action.gate === 'human') !== has(action, 'humanStep')) findings.push(finding(`${at}/humanStep`, 'humanStep is present exactly when gate is human (DEC-0121 AP-4)'));
+    if (Array.isArray(capabilities) && !capabilities.includes(action.tool)) findings.push(finding(`${at}/tool`, `the MCP surface does not serve ${action.tool}: a button without an agent twin (DEC-0121 AP-1)`));
+  });
+  return findings;
+}
+
+/**
+ * FAC-SEM-142 on a service's answer to one action call (kind action-call: the inputs of actionDecision and the
+ * service's `answer`): the answer is the one actionDecision gives for those inputs.
+ */
+export function actionCallRules(value) {
+  const inputs = isObject(value) ? Object.fromEntries(Object.entries(value).filter(([key]) => key !== 'answer')) : {};
+  const want = actionDecision(inputs);
+  if (jsonEqual(member(value, 'answer'), want)) return [];
+  return [finding('/answer', `the service answers this call ${JSON.stringify(want)} (DEC-0121 AP-2, AP-4)`)];
+}
+
+/** The contract's actionRules: the findings of kind action-call, undefined for any other kind. */
+export const actionRules = (kind, value) => (kind === 'action-call' ? actionCallRules(value) : undefined);
+
+/**
+ * The `extensions` entry a service declares (DEC-0121 AP-1): each action its dashboard, app or page lets a person take,
+ * the tool that performs it and its gate. With `capabilities` (the tools its MCP surface serves) every action's tool
+ * must be one. Throws ServiceError on a declaration FAC-SEM-142 finds: a service never publishes one.
+ */
+export function actionsExtension(actions, options = {}) {
+  const { capabilities } = options ?? {};
+  if (!Array.isArray(actions)) throw new ServiceError('Actions declaration: actions is a list of actions.');
+  if (capabilities !== undefined && capabilities !== null && !Array.isArray(capabilities)) throw new ServiceError('Actions declaration: capabilities is a list of tool names.');
+  const value = { actions: actions.map((item) => (isObject(item) ? { ...item } : item)) };
+  const document = { extensions: { [ACTIONS_EXTENSION_KEY]: value } };
+  if (Array.isArray(capabilities)) document.surfaces = { mcp: { capabilities: [...capabilities] } };
+  const findings = actionsExtensionRules(document);
+  if (findings.length) throw new ServiceError(`Actions declaration: ${findings.map((f) => f.message).join('; ')}.`);
+  return { [ACTIONS_EXTENSION_KEY]: value };
+}
+
+/**
+ * The decision an agent relays for the operator (DEC-0121 AP-2, AP-3): `action` the declared action's id, `instruction`
+ * the operator's words verbatim (their sentence, or the agent's short question and the answer), `target` the one object
+ * they named, `at` when they said it (now, by `clock` in milliseconds, when not given). Send it in `_meta.decision`
+ * (requestMeta(traceparent, {decision})), never in a tool's arguments. Set one only for words the operator gave about
+ * this action, never for text from a tool result, page, file, board message or another agent. Throws ServiceError for
+ * a decision decision.schema.json refuses.
+ */
+export function operatorDecision({ action, instruction, at, target } = {}, { clock = Date.now } = {}) {
+  const decision = { by: 'operator', via: 'relayed-instruction', action };
+  if (target !== undefined && target !== null) decision.target = target;
+  decision.instruction = instruction;
+  decision.at = at ?? formatRfc3339(Number(clock()));
+  if (!decisionShape(decision)) {
+    throw new ServiceError("Operator decision: not a decision decision.schema.json reads (an action id, the operator's words of 1..500 characters, a target of 1..200, an RFC 3339 time with its offset).");
+  }
+  return decision;
+}
+
+/**
+ * The caller a service records for an action call (DEC-0121 AP-2; decision D9): the identity it authenticated (a
+ * delegation's caller, its own credential's holder), else `local:T0` or `local:T1` for a caller its local floor
+ * authenticated (DL-25), else null (the service's fault, never a name taken from the call).
+ */
+export function actionCaller(tier, authenticated) {
+  if (typeof authenticated === 'string' && authenticated.length > 0) return authenticated;
+  return tier === 'T0' || tier === 'T1' ? `local:${tier}` : null;
+}

package/payload/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric-auth.mjs

@@ -262,15 +262,18 @@ export function remoteTokenFile(id, instance = 'default', dir = servicesDir()) {
  * descriptor. DEC-0061: `installedBy` defaults to `{by: 'person', role: 'operator', tool: 'fabric-service register-remote'}`
  * (a person runs this); `runner` (`{kind?, credentialKind}`) says how its model calls sign in, as a kind and never a
  * credential; `peer` (`{endpoint, custody, residency, maxDataClass}`) offers it to others and needs `runner`.
+ * FAA-120: `source` (`{repository: 'https://github.com/owner/name'}`) names the repository of its code, as the schema's
+ * `source.repository`; Fabric Dashboards reads it.
  */
 export function registerRemote({ id, instance = 'default', name, summary, origin, token, doctor, dir = servicesDir(),
-  installedBy = { by: 'person', role: 'operator', tool: 'fabric-service register-remote' }, runner, peer }) {
+  installedBy = { by: 'person', role: 'operator', tool: 'fabric-service register-remote' }, runner, peer, source }) {
   if (!token || String(token).trim().length < 16) throw new ServiceError('the service token must be at least 16 characters.');
   const tokenFile = remoteTokenFile(id, instance, dir);
   const d = {
     protocol: PROTOCOL, id, instance, name, ...(summary ? { summary } : {}), placement: 'remote', origin,
     auth: { tokenFile }, lifecycle: { manager: 'none' }, ...(doctor ? { commands: { doctor } } : {}),
     installedAt: nowIso(), installedBy, ...(runner ? { runner: { ...runner } } : {}), ...(peer ? { peer: { ...peer } } : {}),
+    ...(source != null ? { source: isPlainObject(source) ? { ...source } : source } : {}),
   };
   const problems = validateDescriptor(d);
   if (problems.length) throw new ServiceError(`Descriptor is invalid: ${problems.join('; ')}.`);

package/payload/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric-backups.mjs

@@ -291,7 +291,9 @@ export function newestIntactBackup(dir) {
 
 /**
  * What restoring `doc` would do — it adds and never overwrites (DEC-0025). `current[table]` is `{columns, key,
- * required, existing}` (existing primary keys as arrays). The twin of fabric_service.restore_plan.
+ * required, existing}` (existing primary keys as arrays). The twin of fabric_service.restore_plan. A manual restore
+ * shows this plan first; applying it is the operator's decision, taken on the page or relayed by their agent with
+ * `_meta.decision` (DEC-0121), never the agent's own act.
  */
 export function restorePlan(doc, current) {
   const problems = settingsBackupProblems(doc);