metaobjects 0.11.1__tar.gz → 0.12.1__tar.gz

metaobjects-0.12.1/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+*.pyc
+.mypy_cache/
+.pytest_cache/
+

{metaobjects-0.11.1 → metaobjects-0.12.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: metaobjects
-Version: 0.11.1
+Version: 0.12.1
 Summary: Cross-language metadata standard: declare typed entities once, generate idiomatic drift-checked code across languages — Python port.
 Project-URL: Homepage, https://metaobjects.dev
 Project-URL: Repository, https://github.com/metaobjectsdev/metaobjects
@@ -86,6 +86,18 @@ verify), `runtime` (SQLAlchemy-Core object manager), and `migrate`.
   ([ADR-0006](https://github.com/metaobjectsdev/metaobjects/blob/main/spec/decisions/ADR-0006-ai-first-yaml-authoring.md)).
   Desugared to canonical JSON at load time. A directory may mix both freely.
 
+## AI assistant context
+
+To scaffold MetaObjects context files (`.metaobjects/AGENTS.md`, `.metaobjects/CLAUDE.md`, and
+`.claude/skills/metaobjects-*/`) into your project so your AI assistant understands how to
+author metadata and run codegen, use the Node `meta` CLI:
+
+```bash
+npx meta agent-docs --server python
+```
+
+(Running `metaobjects agent-docs` in the Python CLI prints this redirect and exits.)
+
 ## Links
 
 - Standard, docs, and the other four ports: <https://metaobjects.dev>

{metaobjects-0.11.1 → metaobjects-0.12.1}/README.md

@@ -51,6 +51,18 @@ verify), `runtime` (SQLAlchemy-Core object manager), and `migrate`.
   ([ADR-0006](https://github.com/metaobjectsdev/metaobjects/blob/main/spec/decisions/ADR-0006-ai-first-yaml-authoring.md)).
   Desugared to canonical JSON at load time. A directory may mix both freely.
 
+## AI assistant context
+
+To scaffold MetaObjects context files (`.metaobjects/AGENTS.md`, `.metaobjects/CLAUDE.md`, and
+`.claude/skills/metaobjects-*/`) into your project so your AI assistant understands how to
+author metadata and run codegen, use the Node `meta` CLI:
+
+```bash
+npx meta agent-docs --server python
+```
+
+(Running `metaobjects agent-docs` in the Python CLI prints this redirect and exits.)
+
 ## Links
 
 - Standard, docs, and the other four ports: <https://metaobjects.dev>

metaobjects-0.12.1/hatch_build.py

@@ -0,0 +1,15 @@
+"""Build hook — no-op.
+
+The ``agent-context/`` content tree vendoring into ``_content/`` has been removed:
+agent-context scaffolding is now owned by the Node ``meta agent-docs`` CLI. This
+file is kept as a no-op to avoid breaking any build tooling that references it.
+"""
+
+from __future__ import annotations
+
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+
+
+class CustomBuildHook(BuildHookInterface):
+    def initialize(self, version: str, build_data: dict) -> None:
+        pass  # Nothing to vendor — scaffolding moved to the Node meta CLI.

{metaobjects-0.11.1 → metaobjects-0.12.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "metaobjects"
-version = "0.11.1"
+version = "0.12.1"
 description = "Cross-language metadata standard: declare typed entities once, generate idiomatic drift-checked code across languages — Python port."
 readme = "README.md"
 requires-python = ">=3.11"

metaobjects-0.12.1/src/metaobjects/agent_context/__init__.py

@@ -0,0 +1,24 @@
+"""Agent-context staleness nudge — manifest reader for gen/verify.
+
+The assembly path has moved to the Node ``meta agent-docs`` CLI. This package
+now only exposes the staleness-nudge symbols (``agent_context_staleness``,
+``Manifest``, ``AGENT_CONTEXT_MANIFEST_PATH``, ``installed_metaobjects_version``)
+used by ``gen``/``verify`` to detect when the copied-in agent context predates
+the installed MetaObjects version.
+"""
+
+from __future__ import annotations
+
+from .scaffold import (
+    AGENT_CONTEXT_MANIFEST_PATH,
+    Manifest,
+    agent_context_staleness,
+    installed_metaobjects_version,
+)
+
+__all__ = [
+    "AGENT_CONTEXT_MANIFEST_PATH",
+    "Manifest",
+    "agent_context_staleness",
+    "installed_metaobjects_version",
+]

{metaobjects-0.11.1 → metaobjects-0.12.1}/src/metaobjects/agent_context/scaffold.py

@@ -1,24 +1,18 @@
-"""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.
+"""Sidecar manifest + staleness nudge for the agent-context scaffolder.
+
+The assembly path (assemble / plan_scaffold / ScaffoldDecision) has been removed —
+that work is now owned by the Node ``meta agent-docs`` CLI. This module retains
+only the staleness-nudge machinery (``agent_context_staleness``, ``Manifest``,
+``AGENT_CONTEXT_MANIFEST_PATH``, ``installed_metaobjects_version``) which is used
+by ``gen``/``verify`` to detect when the scaffolded agent context predates the
+installed MetaObjects version.
 """
 
 from __future__ import annotations
 
-import hashlib
-from collections.abc import Callable
-from dataclasses import dataclass, field
+from dataclasses import dataclass
 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"
 
@@ -82,89 +76,6 @@ class Manifest:
         )
 
 
-@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:
@@ -186,6 +97,6 @@ def agent_context_staleness(
     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"you're on {current_version}. Run 'npx meta agent-docs --server python' to "
         f"refresh the .claude/skills docs."
     )

{metaobjects-0.11.1 → metaobjects-0.12.1}/src/metaobjects/cli.py

@@ -43,13 +43,8 @@ from pathlib import Path
 from metaobjects import MetaDataLoader
 from metaobjects.agent_context import (
     AGENT_CONTEXT_MANIFEST_PATH,
-    Manifest,
     agent_context_staleness,
-    assemble,
     installed_metaobjects_version,
-    make_stack,
-    plan_scaffold,
-    resolve_agent_context_root,
 )
 from metaobjects.meta.meta_data import MetaData
 from metaobjects.codegen.config import GenConfig
@@ -134,21 +129,37 @@ def _resolve_generators(names: str) -> tuple[list[Generator], list[str]]:
     return gens, errors
 
 
+def _parse_entities(value: str | None) -> list[str] | None:
+    """Parse a comma-separated ``--entities`` value into a name list (``None`` =
+    no filter = generate every entity). Blank names are dropped."""
+    if not value:
+        return None
+    names = [n.strip() for n in value.split(",") if n.strip()]
+    return names or None
+
+
 def _generate(
-    metadata_dir: str, out_dir: str, generators: list[Generator] | None = None
+    metadata_dir: str,
+    out_dir: str,
+    generators: list[Generator] | None = None,
+    entity_filter: list[str] | None = None,
 ) -> tuple[list[str], list[str]]:
     """Run the generator suite into ``out_dir``.
 
     ``generators`` defaults to the zero-config default suite; pass a registry-
-    resolved subset for ``--generators``. Returns ``(written_paths, errors)``. On
-    a load error, ``errors`` is non-empty and no files are written.
+    resolved subset for ``--generators``. ``entity_filter`` (the ``--entities``
+    allowlist) restricts which entities are EMITTED while the WHOLE model is still
+    loaded, so cross-entity references (``extends`` bases, ``@objectRef`` VOs)
+    resolve — emit a subset without splitting the metadata. Returns
+    ``(written_paths, errors)``. On a load error, ``errors`` is non-empty and no
+    files are written.
     """
     root, errors = _load_root(metadata_dir)
     if root is None:
         return [], errors
     config = GenConfig(out_dir=out_dir)
     suite = generators if generators is not None else _default_generators()
-    result = run_gen(config, root, generators=suite)
+    result = run_gen(config, root, generators=suite, entity_filter=entity_filter)
     written = [path for path, status in result.files if status != "refused"]
     return written, []
 
@@ -282,7 +293,8 @@ def _cmd_gen(args: argparse.Namespace) -> int:
                 print(f"  {msg}", file=sys.stderr)
             return 1
 
-    written, errors = _generate(args.metadata_dir, args.out, generators)
+    entities = _parse_entities(getattr(args, "entities", None))
+    written, errors = _generate(args.metadata_dir, args.out, generators, entities)
     if errors:
         print("error: failed to load metadata:", file=sys.stderr)
         for msg in errors:
@@ -322,9 +334,12 @@ def _verify_codegen(args: argparse.Namespace) -> int:
         )
         return 2
 
-    # Reuse the exact gen code path — regenerate into a throwaway temp dir.
+    # Reuse the exact gen code path — regenerate into a throwaway temp dir. The
+    # --entities filter must match the `gen` that produced --out, or the diff
+    # reports the un-emitted entities as spurious drift.
     with tempfile.TemporaryDirectory() as tmp:
-        written, errors = _generate(args.metadata_dir, tmp)
+        entities = _parse_entities(getattr(args, "entities", None))
+        written, errors = _generate(args.metadata_dir, tmp, None, entities)
         if errors:
             print("error: failed to load metadata:", file=sys.stderr)
             for msg in errors:
@@ -521,129 +536,14 @@ def _cmd_verify(args: argparse.Namespace) -> int:
     return exit_code
 
 
-#: The root-doc filenames we look for / create, and the line we append so a
-#: Claude Code agent always picks up the slim always-on context.
-_ROOT_DOC_CANDIDATES = ("CLAUDE.md", "AGENTS.md")
-_ROOT_DOC_IMPORT_LINE = "@.metaobjects/AGENTS.md"
-
-
-def _detect_python_server(out_dir: Path) -> bool:
-    """Simple stack detection: a ``pyproject.toml`` in --out marks a Python project."""
-    return (out_dir / "pyproject.toml").is_file()
-
-
-def _wire_root_doc(out_dir: Path) -> str | None:
-    """Append ``@.metaobjects/AGENTS.md`` to the root CLAUDE.md/AGENTS.md.
-
-    Idempotent — if the import line is already present in either doc, do nothing.
-    If neither doc exists, create ``CLAUDE.md`` with the import line. Returns the
-    doc filename that was created/updated, or ``None`` if it was already wired.
-    """
-    existing = [name for name in _ROOT_DOC_CANDIDATES if (out_dir / name).is_file()]
-    # Already wired in any existing doc → idempotent no-op.
-    for name in existing:
-        text = (out_dir / name).read_text(encoding="utf-8")
-        if _ROOT_DOC_IMPORT_LINE in text:
-            return None
-
-    if existing:
-        target = out_dir / existing[0]
-        text = target.read_text(encoding="utf-8")
-        sep = "" if text.endswith("\n") or text == "" else "\n"
-        target.write_text(f"{text}{sep}{_ROOT_DOC_IMPORT_LINE}\n", encoding="utf-8")
-        return existing[0]
-
-    target = out_dir / "CLAUDE.md"
-    target.write_text(f"{_ROOT_DOC_IMPORT_LINE}\n", encoding="utf-8")
-    return "CLAUDE.md"
-
-
 def _cmd_agent_docs(args: argparse.Namespace) -> int:
-    """``agent-docs`` — scaffold the slim MetaObjects Claude Code agent context.
-
-    Resolve the stack from ``--server`` / ``--client`` (repeatable). With neither,
-    detect ``pyproject.toml`` → a python server. Assemble against the bundled
-    content tree, then write the files into ``--out`` (default cwd): each new or
-    manifest-unmodified file is written at its path; a hand-edited file's fresh
-    contents go to ``<path>.new``. Append the always-on import to a root
-    CLAUDE.md/AGENTS.md (idempotent), and persist the sidecar manifest.
-    """
-    out_dir = Path(args.out).resolve() if args.out else Path.cwd()
-
-    servers = list(args.server or [])
-    clients = list(args.client or [])
-    if not servers and not clients:
-        if _detect_python_server(out_dir):
-            servers = ["python"]
-        else:
-            print(
-                "error: no --server/--client given and no pyproject.toml found to "
-                "detect a stack. Pass at least one --server or --client.",
-                file=sys.stderr,
-            )
-            return 2
-
-    try:
-        content_root = resolve_agent_context_root()
-    except FileNotFoundError as e:
-        print(f"error: {e}", file=sys.stderr)
-        return 1
-
-    stack = make_stack(servers, clients)
-    assembled = assemble(content_root, stack)
-
-    # Load the prior manifest, if any, so hand-edits are preserved on re-run.
-    manifest_path = out_dir / AGENT_CONTEXT_MANIFEST_PATH
-    prior: Manifest | None = None
-    if manifest_path.is_file():
-        try:
-            prior = Manifest.from_json(
-                json.loads(manifest_path.read_text(encoding="utf-8"))
-            )
-        except (json.JSONDecodeError, ValueError, KeyError):
-            prior = None  # corrupt sidecar → treat as a fresh scaffold
-
-    def _read_current(rel: str) -> str | None:
-        p = out_dir / rel
-        return p.read_bytes().decode("utf-8") if p.is_file() else None
-
-    decision = plan_scaffold(
-        stack,
-        assembled,
-        prior,
-        _read_current,
-        generated_by=installed_metaobjects_version(),
-    )
-
-    for w in decision.writes:
-        dest = out_dir / w.path
-        dest.parent.mkdir(parents=True, exist_ok=True)
-        dest.write_bytes(w.contents.encode("utf-8"))
-        print(f"wrote {w.path}")
-    for c in decision.conflicts:
-        dest = out_dir / c.new_path
-        dest.parent.mkdir(parents=True, exist_ok=True)
-        dest.write_bytes(c.contents.encode("utf-8"))
-        print(f"hand-edited; wrote fresh copy to {c.new_path} (kept your {c.path})")
-    for rel in decision.removed:
-        print(f"note: {rel} no longer applies to this stack (not deleted)")
-
-    # Persist the manifest.
-    assert decision.manifest is not None
-    manifest_path.parent.mkdir(parents=True, exist_ok=True)
-    manifest_path.write_text(
-        json.dumps(decision.manifest.to_json(), indent=2) + "\n", encoding="utf-8"
-    )
-
-    wired = _wire_root_doc(out_dir)
-    if wired is not None:
-        print(f"wired {_ROOT_DOC_IMPORT_LINE} into {wired}")
-
+    """``agent-docs`` — redirect to the canonical Node meta CLI scaffolder."""
     print(
-        f"metaobjects agent-docs: scaffolded {len(assembled)} file(s) for stack "
-        f"servers={list(stack.servers)} clients={list(stack.clients)} under {out_dir}"
+        "agent-context scaffolding moved to the meta CLI — run: "
+        "npx meta agent-docs --server python [--client <fw>] [--out <dir>]",
+        file=sys.stderr,
     )
-    return 0
+    return 1
 
 
 def _build_parser() -> argparse.ArgumentParser:
@@ -686,6 +586,15 @@ def _build_parser() -> argparse.ArgumentParser:
         default=None,
         help="(reserved) package hint; Python derives package from metadata",
     )
+    gen.add_argument(
+        "--entities",
+        default=None,
+        help=(
+            "comma-separated entity NAMES to emit (allowlist). The whole model is "
+            "still loaded so `extends` bases and @objectRef VOs resolve; only the "
+            "named entities are written. Omit to emit every entity."
+        ),
+    )
     gen.set_defaults(func=_cmd_gen)
 
     docs = sub.add_parser(
@@ -758,6 +667,11 @@ def _build_parser() -> argparse.ArgumentParser:
         default=None,
         help="on-disk template/prompt dir the --templates gate resolves refs against",
     )
+    verify.add_argument(
+        "--entities",
+        default=None,
+        help="comma-separated entity allowlist for --codegen drift (match `gen --entities`)",
+    )
     verify.set_defaults(func=_cmd_verify)
 
     agent_docs = sub.add_parser(

{metaobjects-0.11.1 → metaobjects-0.12.1}/src/metaobjects/codegen/generators/entity_model.py

@@ -1,6 +1,8 @@
 """object.* → Pydantic v2 model module (sub-project A)."""
 from __future__ import annotations
 
+import re
+
 from metaobjects.meta.core.field.meta_field import MetaField
 from metaobjects.meta.core.object.meta_object import MetaObject
 from metaobjects.meta.core.field import field_constants as fc
@@ -25,6 +27,27 @@ def _is_int(value: object) -> bool:
     return isinstance(value, int) and not isinstance(value, bool)
 
 
+# SQL expression defaults: anything matching is a SERVER-side default (the DB fills
+# it), NOT a Python literal default — so `@default: gen_random_uuid()` must not emit
+# `id: uuid.UUID = "gen_random_uuid()"`. Mirrors the TS column-mapper's
+# SQL_EXPR_PATTERNS (and migrate-ts EXPR_DEFAULT_PATTERNS) so every port agrees on
+# what counts as an expression.
+_SQL_EXPR_DEFAULT_PATTERNS = (
+    re.compile(r"^now$", re.I),
+    re.compile(r"^now\(\)$", re.I),
+    re.compile(r"^current_timestamp$", re.I),
+    re.compile(r"^current_date$", re.I),
+    re.compile(r"^current_time$", re.I),
+    re.compile(r"\(\)$"),  # anything function-like, e.g. gen_random_uuid()
+)
+
+
+def _is_sql_expr_default(value: object) -> bool:
+    """True iff *value* is a server-side SQL expression default (DB-filled), not a
+    Python literal. Only string defaults can be expressions."""
+    return isinstance(value, str) and any(p.search(value) for p in _SQL_EXPR_DEFAULT_PATTERNS)
+
+
 def _validators(field: MetaField, sub_type: str) -> list[MetaField]:
     """The field's own ``validator.<sub_type>`` children (effective, supers included)."""
     return [
@@ -121,7 +144,10 @@ def _field_line(field: MetaField, imports: set[str], config: GenConfig) -> tuple
             imports.add(f"from .{ref_name} import {ref_name}")
     required = field.attrs().get(fc.FIELD_ATTR_REQUIRED) is True
     default_raw = field.attrs().get(fc.FIELD_ATTR_DEFAULT)
-    has_default = default_raw is not None
+    # A server-side expression default (now(), gen_random_uuid(), CURRENT_TIMESTAMP)
+    # is filled by the DB — the Python model carries no default for it (the field keeps
+    # its required/optional shape). Only literal defaults become Pydantic defaults.
+    has_default = default_raw is not None and not _is_sql_expr_default(default_raw)
     enum_type_name = type_name if shared is not None else None
 
     constraints = _validator_constraints(field)
@@ -154,7 +180,13 @@ def _field_line(field: MetaField, imports: set[str], config: GenConfig) -> tuple
     else:
         assignment = " = None"
 
-    return f"    {field.name}: {annotation}{assignment}", uses_field
+    # Pydantic field name = @column when present, else field.name. A cross-port
+    # entity carries the camelCase field.name (the TS property) AND the snake_case
+    # @column (the physical DB column); the Python model field IS the column, so it
+    # binds straight to the row. Backward-compatible: snake-authored models with no
+    # @column emit field.name unchanged.
+    py_name = field.attrs().get(fc.FIELD_ATTR_COLUMN) or field.name
+    return f"    {py_name}: {annotation}{assignment}", uses_field
 
 
 def _effective_fqn(entity: MetaObject) -> str: