metaobjects 0.9.0__py3-none-any.whl

metaobjects/agent_context/_content/templates/always-on.md.mustache

@@ -0,0 +1,27 @@
+# Working with MetaObjects in this project
+
+> {{stackLine}}
+
+MetaObjects is a metadata standard: typed metadata in `metaobjects/` is the durable
+spine; generated code is the disposable artifact. Regenerate with `{{codegenCommand}}`.
+
+## Principles
+- Pattern-derivable from metadata = codegen, never hand-write (FKs, CRUD, validators, finders).
+- Never hand-edit generated files — change the metadata and regenerate (three-way merge preserves hand-written regions).
+- Use the generated constants for any string that names metadata.
+- The loaded metadata model is READ-ONLY — never inject nodes or mutate the tree at load time (no "enrich the model on load" hooks). Need an extra field/column? Author it in the metadata, or derive it during codegen (read the metadata, emit output). Mutating the loaded model makes it diverge from what's declared — a bad practice reserved for very rare cases.
+
+## Authoring rules you must not violate
+- Nodes are fused-key maps: `{"<type>.<subType>": { ... }}` (e.g. `{"field.string": {"name": "email"}}`) — never split the type and subtype into separate keys.
+- Attribute names are unique within a node; for multi-value use one array attr (`@values: [...]`).
+- An inline `@maxLength: 50` equals an `attr` child of the same name — never write both.
+- Package paths use `::` (`acme::common::id`).
+
+## Going deeper (Claude Code)
+For authoring, codegen, runtime/UI, prompts, or verify work, use the matching
+`metaobjects-*` skill — its body links the `references/<lang>.md` fragment installed
+for this project's stack.
+
+These `metaobjects-*` skills are plain, inspectable Markdown reference docs (no tools
+or hooks) generated by MetaObjects for this project's stack — safe to read and edit;
+re-run the agent-context scaffold to refresh them.

metaobjects/agent_context/assemble.py

@@ -0,0 +1,133 @@
+"""The pure agent-context assembler.
+
+Port of ``server/typescript/packages/sdk/src/agent-context/assemble.ts``. Given
+the content tree and a resolved :class:`Stack`, produce the ``(path, contents)``
+files the consumer project receives — byte-identical to the TS reference.
+
+BYTE-IDENTITY: every file but the two always-on documents is a verbatim copy.
+We read with ``Path.read_bytes().decode("utf-8")`` (NOT ``open(... )`` text mode)
+so Python never translates newlines, and emit ``str`` whose UTF-8 encoding is the
+original bytes. The only computed content is the two template substitutions.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from .types import (
+    CLIENT_FRAMEWORKS,
+    MIGRATION_TOKEN,
+    SERVER_LANGS,
+    SKILL_NAMES,
+    Stack,
+)
+
+#: ``{{key}}`` template-variable pattern (word chars only, matching the TS regex).
+_TEMPLATE_VAR = re.compile(r"\{\{(\w+)\}\}")
+
+
+@dataclass(frozen=True)
+class AssembledFile:
+    """A file the assembler emits, ``path`` relative to the consumer project root."""
+
+    path: str
+    contents: str
+
+
+def make_stack(servers: list[str], clients: list[str]) -> Stack:
+    """Build a :class:`Stack`: dedupe + canonical-order the inputs, derive tokens.
+
+    Unknown entries are dropped (the canonical orderings are the allow-list); the
+    resulting orderings are exactly :data:`SERVER_LANGS` / :data:`CLIENT_FRAMEWORKS`
+    filtered to the requested set, matching the TS ``makeStack``.
+    """
+    s = tuple(x for x in SERVER_LANGS if x in servers)
+    c = tuple(x for x in CLIENT_FRAMEWORKS if x in clients)
+    tokens = frozenset({*s, *c, MIGRATION_TOKEN})
+    return Stack(servers=s, clients=c, tokens=tokens)
+
+
+def _read_text(path: Path) -> str:
+    """Read a file as UTF-8 with NO newline translation (byte-faithful)."""
+    return path.read_bytes().decode("utf-8")
+
+
+def _read_server_meta(content_root: Path, server: str) -> dict[str, str] | None:
+    """Load ``servers/<server>.meta.json``, or ``None`` if absent."""
+    p = content_root / "servers" / f"{server}.meta.json"
+    if not p.exists():
+        return None
+    return json.loads(_read_text(p))
+
+
+def _stack_line(content_root: Path, stack: Stack) -> tuple[str, str]:
+    """Compute ``(stackLine, codegenCommand)`` for the always-on template.
+
+    ``codegenCommand`` is the FIRST server's ``codegenCommand`` (or ``"meta gen"``
+    if there is no primary server, or its meta file is absent).
+    """
+    primary = stack.servers[0] if stack.servers else None
+    meta = _read_server_meta(content_root, primary) if primary else None
+    server_part = ", ".join(stack.servers) + " server" if stack.servers else "no server"
+    client_part = ", ".join(stack.clients) + " client" if stack.clients else "no client"
+    line = f"Stack: {server_part}, {client_part}; migrations are TS."
+    codegen_command = meta["codegenCommand"] if meta else "meta gen"
+    return line, codegen_command
+
+
+def _apply_template(tpl: str, variables: dict[str, str]) -> str:
+    """Replace every ``{{key}}``; raise on an unknown key (matches TS)."""
+
+    def repl(match: re.Match[str]) -> str:
+        key = match.group(1)
+        if key not in variables:
+            raise ValueError(f"agent-context: unknown template variable {{{{{key}}}}}")
+        return variables[key]
+
+    return _TEMPLATE_VAR.sub(repl, tpl)
+
+
+def assemble(content_root: Path, stack: Stack) -> list[AssembledFile]:
+    """Assemble the consumer files for a resolved stack. Pure given the content tree.
+
+    Output is sorted by path ascending — the stable order the conformance gate and
+    the TS reference both produce.
+    """
+    out: list[AssembledFile] = []
+
+    # 1. Always-on (AGENTS.md + CLAUDE.md, identical contents).
+    tpl = _read_text(content_root / "templates" / "always-on.md.mustache")
+    line, codegen_command = _stack_line(content_root, stack)
+    always_on = _apply_template(
+        tpl, {"stackLine": line, "codegenCommand": codegen_command}
+    )
+    out.append(AssembledFile(".metaobjects/AGENTS.md", always_on))
+    out.append(AssembledFile(".metaobjects/CLAUDE.md", always_on))
+
+    # 2. Skills: body + only the references whose token is in the stack.
+    for skill in SKILL_NAMES:
+        skill_dir = content_root / "skills" / skill
+        body = _read_text(skill_dir / "SKILL.md")
+        out.append(AssembledFile(f".claude/skills/{skill}/SKILL.md", body))
+
+        ref_dir = skill_dir / "references"
+        if ref_dir.is_dir():
+            tokens = sorted(
+                p.stem
+                for p in ref_dir.iterdir()
+                if p.is_file() and p.suffix == ".md" and p.stem in stack.tokens
+            )
+            for token in tokens:
+                out.append(
+                    AssembledFile(
+                        f".claude/skills/{skill}/references/{token}.md",
+                        _read_text(ref_dir / f"{token}.md"),
+                    )
+                )
+
+    # Stable order: by path.
+    out.sort(key=lambda f: f.path)
+    return out

metaobjects/agent_context/content_root.py

@@ -0,0 +1,54 @@
+"""Resolve the ``agent-context/`` content tree the assembler reads.
+
+Two resolution sources (matching the TS reference's bundled-then-monorepo walk):
+
+1. A bundled copy shipped inside the installed wheel, at
+   ``metaobjects/agent_context/_content/`` (vendored at build time by the custom
+   hatch build hook ``hatch_build.py``). This is the published path.
+2. A dev fallback: walk up from this module to the monorepo root and use its
+   top-level ``agent-context/`` directory.
+
+A directory is a valid content root iff it holds the authoring skill body.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+#: Where the bundled copy lands inside the package (see pyproject force-include).
+_BUNDLED = Path(__file__).resolve().parent / "_content"
+
+
+def _is_content_root(directory: Path) -> bool:
+    """A directory is a valid content root iff it holds the authoring skill body."""
+    return (directory / "skills" / "metaobjects-authoring" / "SKILL.md").is_file()
+
+
+def resolve_agent_context_root(override: Path | None = None) -> Path:
+    """Resolve the content tree.
+
+    - If ``override`` is given, it must be a valid content root (else raise).
+    - Else: prefer the bundled copy beside this module (published path); fall back
+      to a monorepo ``agent-context/`` found by walking up from this module (dev).
+    """
+    if override is not None:
+        if _is_content_root(override):
+            return override
+        raise FileNotFoundError(
+            f"agent-context content not found at override: {override}"
+        )
+
+    if _is_content_root(_BUNDLED):
+        return _BUNDLED
+
+    here = Path(__file__).resolve()
+    for parent in here.parents:
+        candidate = parent / "agent-context"
+        if _is_content_root(candidate):
+            return candidate
+
+    raise FileNotFoundError(
+        "agent-context content not found — looked for a bundled copy beside the "
+        "package (metaobjects/agent_context/_content) and a monorepo "
+        "`agent-context/` walking up from this module."
+    )

metaobjects/agent_context/scaffold.py

@@ -0,0 +1,191 @@
+"""Scaffold planning + sidecar manifest for the agent-context writer.
+
+Port of ``server/typescript/packages/sdk/src/agent-context/scaffold.ts``. Pure:
+all filesystem access is via a ``read_current`` callback so the planning logic is
+testable without touching disk.
+
+A file is safe to overwrite iff it is absent, or its on-disk sha256 still equals
+the hash the prior manifest recorded (the user hasn't hand-edited it). A
+hand-edited file is preserved — the fresh contents go to ``<path>.new`` instead.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from importlib.metadata import PackageNotFoundError, version as _pkg_version
+
+from .assemble import AssembledFile
+from .types import Stack
+
+#: Consumer-relative path of the sidecar manifest that tracks scaffolded files.
+AGENT_CONTEXT_MANIFEST_PATH = ".metaobjects/.agent-context.json"
+
+
+def installed_metaobjects_version() -> str:
+    """The installed ``metaobjects`` distribution version, or ``"0.0.0"`` if absent.
+
+    Resolved idiomatically via :func:`importlib.metadata.version`; a
+    ``PackageNotFoundError`` (e.g. running straight from a source checkout that
+    was never installed) falls back to ``"0.0.0"`` — mirroring the TS reference's
+    fallback so the stamp/nudge never crashes.
+    """
+    try:
+        return _pkg_version("metaobjects")
+    except PackageNotFoundError:
+        return "0.0.0"
+
+
+@dataclass
+class Manifest:
+    """Tracks what the assembler last wrote, so re-runs can detect hand-edits."""
+
+    version: int
+    servers: list[str]
+    clients: list[str]
+    #: consumer-relative path → sha256 of the contents as last scaffolded.
+    files: dict[str, str]
+    #: The MetaObjects version that last scaffolded this context. Drives the
+    #: staleness nudge (an upgrade can leave the copied-in skills/docs stale).
+    #: Optional for back-compat with manifests written before version tracking.
+    #: Serialized as ``generatedBy`` — the SAME key as the TS reference, so a
+    #: polyglot repo can cross-read the manifest regardless of which port wrote it.
+    generated_by: str | None = None
+
+    def to_json(self) -> dict[str, object]:
+        out: dict[str, object] = {"version": self.version}
+        if self.generated_by is not None:
+            out["generatedBy"] = self.generated_by
+        out["servers"] = list(self.servers)
+        out["clients"] = list(self.clients)
+        out["files"] = dict(self.files)
+        return out
+
+    @staticmethod
+    def from_json(data: dict[str, object]) -> "Manifest":
+        files_raw = data.get("files", {})
+        files = (
+            {str(k): str(v) for k, v in files_raw.items()}
+            if isinstance(files_raw, dict)
+            else {}
+        )
+        servers = data.get("servers", [])
+        clients = data.get("clients", [])
+        generated_by = data.get("generatedBy")
+        return Manifest(
+            version=int(data.get("version", 1)),  # type: ignore[arg-type]
+            servers=[str(x) for x in servers] if isinstance(servers, list) else [],
+            clients=[str(x) for x in clients] if isinstance(clients, list) else [],
+            files=files,
+            generated_by=str(generated_by) if generated_by is not None else None,
+        )
+
+
+@dataclass
+class _Write:
+    path: str
+    contents: str
+
+
+@dataclass
+class _Conflict:
+    path: str
+    new_path: str
+    contents: str
+
+
+@dataclass
+class ScaffoldDecision:
+    """The outcome of planning a (re-)scaffold."""
+
+    #: files to (over)write at their own path: new, or unmodified-since-last-scaffold.
+    writes: list[_Write] = field(default_factory=list)
+    #: hand-edited files: write the fresh contents to ``<path>.new``, leave the original.
+    conflicts: list[_Conflict] = field(default_factory=list)
+    #: the manifest to persist after writing.
+    manifest: Manifest | None = None
+    #: paths the prior manifest tracked that are no longer assembled — reported, never deleted.
+    removed: list[str] = field(default_factory=list)
+
+
+def hash_contents(s: str) -> str:
+    """sha256 hex of the UTF-8 bytes of ``s`` (matches the TS digest)."""
+    return hashlib.sha256(s.encode("utf-8")).hexdigest()
+
+
+def plan_scaffold(
+    stack: Stack,
+    assembled: list[AssembledFile],
+    prior: Manifest | None,
+    read_current: Callable[[str], str | None],
+    generated_by: str | None = None,
+) -> ScaffoldDecision:
+    """Decide what to write for a (re-)scaffold (pure; FS via ``read_current``).
+
+    ``generated_by`` is the MetaObjects version doing the scaffold — stamped into
+    the persisted manifest so a later ``gen``/``verify`` can detect staleness.
+    """
+    writes: list[_Write] = []
+    conflicts: list[_Conflict] = []
+    files: dict[str, str] = {}
+
+    for f in assembled:
+        files[f.path] = hash_contents(f.contents)
+        current = read_current(f.path)
+        if current is None:
+            writes.append(_Write(path=f.path, contents=f.contents))
+            continue
+        prior_hash = prior.files.get(f.path) if prior else None
+        if prior_hash is not None and hash_contents(current) == prior_hash:
+            writes.append(_Write(path=f.path, contents=f.contents))  # refresh
+        else:
+            conflicts.append(
+                _Conflict(
+                    path=f.path, new_path=f"{f.path}.new", contents=f.contents
+                )
+            )
+
+    assembled_paths = {f.path for f in assembled}
+    removed = (
+        [p for p in prior.files if p not in assembled_paths] if prior else []
+    )
+
+    return ScaffoldDecision(
+        writes=writes,
+        conflicts=conflicts,
+        manifest=Manifest(
+            version=1,
+            servers=list(stack.servers),
+            clients=list(stack.clients),
+            files=files,
+            generated_by=generated_by,
+        ),
+        removed=removed,
+    )
+
+
+def agent_context_staleness(
+    manifest: dict[str, object] | None, current_version: str
+) -> str | None:
+    """One-line nudge if the scaffolded agent context predates the install.
+
+    Returns ``None`` when there is nothing to say — no agent context here, or it
+    is in sync — and a one-line advisory message otherwise. Pure + advisory:
+    never raises, never blocks, never writes.
+
+    The comparison is **exact equality** on purpose: ANY drift nudges (a
+    re-scaffold is cheap + idempotent). Do NOT "fix" this into a semver compare —
+    a prerelease/build-metadata difference is still a reason to refresh.
+    """
+    if manifest is None:
+        return None  # no agent context here → nothing to nudge
+    generated_by = manifest.get("generatedBy")
+    if generated_by == current_version:
+        return None  # in sync
+    frm = generated_by if generated_by else "an older MetaObjects"
+    return (
+        f"MetaObjects agent context was generated by {frm}; "
+        f"you're on {current_version}. Re-run 'metaobjects agent-docs' to "
+        f"refresh the .claude/skills docs."
+    )

metaobjects/agent_context/types.py

@@ -0,0 +1,44 @@
+"""Stack vocabulary for the agent-context assembler.
+
+These constants are the cross-port contract — they must match the TypeScript
+reference (``server/typescript/packages/sdk/src/agent-context/types.ts``) exactly:
+the SERVER/CLIENT orderings determine dedupe order, and the skill list + its
+order is load-bearing for byte-identical output.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+#: Server languages, in canonical dedupe order.
+SERVER_LANGS: tuple[str, ...] = ("typescript", "java", "kotlin", "csharp", "python")
+
+#: Client frameworks, in canonical dedupe order.
+CLIENT_FRAMEWORKS: tuple[str, ...] = ("react", "tanstack", "angular")
+
+#: Always-present token: schema migrations are TS-owned for every port (ADR-0015).
+MIGRATION_TOKEN = "migration"
+
+#: The five skills, in the exact emit order (matches the TS reference).
+SKILL_NAMES: tuple[str, ...] = (
+    "metaobjects-authoring",
+    "metaobjects-codegen",
+    "metaobjects-runtime-ui",
+    "metaobjects-prompts",
+    "metaobjects-verify",
+)
+
+
+@dataclass(frozen=True)
+class Stack:
+    """The resolved tech-stack of a consumer project.
+
+    - ``servers`` — deduped, in :data:`SERVER_LANGS` order.
+    - ``clients`` — deduped, in :data:`CLIENT_FRAMEWORKS` order.
+    - ``tokens`` — ``servers ∪ clients ∪ {"migration"}``, the install-selection
+      set used to choose which reference fragments to emit.
+    """
+
+    servers: tuple[str, ...]
+    clients: tuple[str, ...]
+    tokens: frozenset[str]

metaobjects/attr_class_map.py

@@ -0,0 +1,23 @@
+"""Dependency-free registry: attr subtype -> MetaAttr class. Breaks the meta-data import cycle."""
+from __future__ import annotations
+
+from typing import Callable
+
+_ATTR_CLASSES: dict[str, Callable[..., object]] = {}
+_FALLBACK: Callable[..., object] | None = None
+
+
+def register_attr_class(sub_type: str, ctor: Callable[..., object]) -> None:
+    _ATTR_CLASSES[sub_type] = ctor
+
+
+def register_fallback_attr_class(ctor: Callable[..., object]) -> None:
+    global _FALLBACK
+    _FALLBACK = ctor
+
+
+def attr_class_for(sub_type: str) -> Callable[..., object]:
+    ctor = _ATTR_CLASSES.get(sub_type, _FALLBACK)
+    if ctor is None:
+        raise RuntimeError("attr classes not registered (import metaobjects.core_types first)")
+    return ctor