gitcad 0.7.7__py3-none-any.whl

gitcad/fasteners.py

@@ -0,0 +1,112 @@
+"""Fastener generation — Toolbox, agent-first (SW-map P6).
+
+Every mounting hole already publishes a ``mech.bolt`` port (ADR-0008);
+this module closes the loop: a parametric socket-head bolt FAMILY
+(P1 parameters + P2 configurations — one document, every length) and a
+generator that walks an assembly's unmated ``mech.bolt`` ports, adds a
+correctly sized bolt instance at each, and MATES it — so the standard
+assembly validation (position coincidence, type compatibility) is the
+proof that every screw is where a screw belongs.
+
+Sizing: the port's ``spec["thread"]`` ("M3") picks the diameter;
+``spec["length"]`` or the caller's default picks the length. Ports with
+no thread spec are reported, never guessed.
+"""
+
+from __future__ import annotations
+
+import re
+
+from gitcad.document import Document, Feature
+from gitcad.errors import GitcadError
+from gitcad.part import Frame, Interface, PartManifest, Port
+
+# ISO 4762 socket head cap screw proportions: head Ø = 1.5d, head height = d
+_STD_LENGTHS = (4, 6, 8, 10, 12, 16, 20, 25, 30)
+
+
+def bolt_family(d: float) -> Document:
+    """A parametric socket-head cap screw as ONE document: parameters for
+    every dimension, one configuration per standard length (P1 + P2 doing
+    what Toolbox does with thousands of files)."""
+    doc = Document()
+    doc.set_parameter("d", d)
+    doc.set_parameter("L", _STD_LENGTHS[2])
+    doc.set_parameter("head_d", "=d*1.5")
+    doc.set_parameter("head_h", "=d")
+    shaft = doc.add(Feature(op="cylinder",
+                            params={"radius": "=d/2", "height": "=L"}))
+    head = doc.add(Feature(op="cylinder",
+                           params={"radius": "=head_d/2", "height": "=head_h"}))
+    head_up = doc.add(Feature(op="move", params={"translate": [0, 0, "=L"]},
+                              inputs=[head]))
+    doc.add(Feature(op="boolean", params={"kind": "union"},
+                    inputs=[shaft, head_up]))
+    for length in _STD_LENGTHS:
+        doc.set_configuration(f"M{d:g}x{length}", {"L": length})
+    return doc
+
+
+def bolt_part(thread: str, length: float) -> PartManifest:
+    """The bolt as a part: envelope from its dimensions, one ``mech.bolt``
+    port at the head seat (origin, -z shaft) — the thing that mates into a
+    mounting hole's port."""
+    d = _thread_diameter(thread)
+    head_d, head_h = 1.5 * d, d
+    iface = Interface(
+        envelope={"origin": [-head_d / 2, -head_d / 2, 0],
+                  "dx": head_d, "dy": head_d, "dz": length + head_h},
+        frames={"seat": Frame()},
+        ports={"seat": Port(name="seat", type="mech.bolt", frame="seat",
+                            spec={"thread": thread, "length": length})},
+        properties={"standard": "ISO4762", "thread": thread, "length": length},
+    )
+    safe = f"{thread}x{length:g}".replace(".", "_")
+    return PartManifest(id=f"prt_bolt_{safe.lower()}", name=f"{thread}x{length:g} SHCS",
+                        domain="mech", version="1.0.0", interface=iface,
+                        body={"kind": "fastener", "standard": "ISO4762"})
+
+
+def generate_fasteners(assembly, *, default_length: float = 8.0) -> dict:
+    """Populate every unmated ``mech.bolt`` port with a sized bolt instance
+    + mate. Returns {"added": [...], "skipped": [...]} — skipped ports name
+    their reason (already mated / no thread spec), never silently."""
+    mated: set[tuple[str, str]] = set()
+    for m in assembly.mates:
+        (ia, pa), (ib, pb) = m.split()
+        mated.add((ia, pa))
+        mated.add((ib, pb))
+
+    added: list[dict] = []
+    skipped: list[dict] = []
+    for iname, inst in sorted(assembly.instances.items()):
+        if inst.part.body.get("kind") == "fastener":
+            continue
+        for pname, port in sorted(inst.part.interface.ports.items()):
+            if port.type != "mech.bolt":
+                continue
+            if (iname, pname) in mated:
+                skipped.append({"port": f"{iname}.{pname}", "reason": "already-mated"})
+                continue
+            thread = (port.spec or {}).get("thread")
+            if not thread:
+                skipped.append({"port": f"{iname}.{pname}", "reason": "no-thread-spec"})
+                continue
+            length = float((port.spec or {}).get("length", default_length))
+            part = bolt_part(thread, length)
+            bolt_name = f"bolt_{iname}_{pname}"
+            pos = inst.port_position(pname)
+            assembly.add(bolt_name, part, translate=pos)
+            assembly.mate(f"{bolt_name}.seat", f"{iname}.{pname}")
+            added.append({"instance": bolt_name, "port": f"{iname}.{pname}",
+                          "thread": thread, "length": length,
+                          "position": list(pos)})
+    return {"added": added, "skipped": skipped}
+
+
+def _thread_diameter(thread: str) -> float:
+    m = re.fullmatch(r"[Mm](\d+(?:\.\d+)?)", thread.strip())
+    if not m:
+        raise GitcadError(
+            f"unsupported thread spec {thread!r} (want metric 'M<d>', e.g. 'M3')")
+    return float(m.group(1))

gitcad/init.py

@@ -0,0 +1,134 @@
+"""gitcad init — a new project in one command.
+
+A gitcad project IS a git repo; this scaffolds the anatomy and seeds
+``<name>.gitcad`` — THE project root: the top-level assembly manifest
+whose instances are the product's parts, mechanical and electrical alike
+(an assembly IS a part, ADR-0008; a board-backed part is an instance like
+any other). Mech feature-tree models are ``.model`` files referenced from
+a part's body — a model is how one part gets its shape, never the product.
+
+Also wired: the semantic merge driver (.gitattributes + git config), a CI
+workflow running the review gate and the requirements suite, and a README
+that explains the layout to the next person who clones it.
+
+Extensions are directory legibility only — every tool detects document
+kind by CONTENT (the schema field), and the old *.json names remain
+accepted everywhere, forever.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+from gitcad.canonical import canonical_json
+from gitcad.errors import GitcadError
+
+_GITATTRIBUTES = """\
+# gitcad semantic merge (ADR-0016): features by stable id, schematic
+# connectivity by pin — never line-level merges of canonical JSON.
+*.gitcad merge=gitcad
+*.model  merge=gitcad
+*.sch    merge=gitcad
+*.board  merge=gitcad
+*.part   merge=gitcad
+*.pcba   merge=gitcad
+"""
+
+_WORKFLOW = """\
+name: gitcad
+on: [push, pull_request]
+jobs:
+  checks:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with: {fetch-depth: 0}
+      - uses: actions/setup-python@v5
+        with: {python-version: "3.12"}
+      - run: pip install gitcad
+      - name: requirements suite
+        run: gitcad-verify requirements.reqs
+      - name: review gate (PRs)
+        if: github.event_name == 'pull_request'
+        run: gitcad-review --base origin/${{ github.base_ref }}
+"""
+
+_README = """\
+# {name}
+
+A [gitcad](https://gitcad.xyz) project — the repo IS the project.
+
+| file | what it is |
+|------|-----------|
+| `{name}.gitcad` | THE project: the top-level assembly of every part, mechanical and electrical |
+| `*.part`   | part manifests (envelope / frames / typed ports; subassemblies are parts too) |
+| `*.model`  | mechanical feature-tree models (canonical text; geometry is a build artifact) |
+| `*.pcba`   | electrical assemblies — mechanical from outside, enter for the electrical workflow |
+| `*.sch`    | schematics — the electrical source of truth |
+| `*.board`  | board layouts |
+| `requirements.reqs` | executable requirements — `gitcad-verify` runs them |
+| `release-*/` | built artifacts + `*.lot` fab-lot provenance records |
+
+Branch = design variant. PR = design review with physics
+(`gitcad-review`). Tag + lot record = a physical production run.
+Merges are semantic (`gitcad-merge`, wired in `.gitattributes`).
+View locally: `gitcad-view <file>`.
+"""
+
+
+def init_project(path: str, *, name: str | None = None) -> list[str]:
+    """Scaffold a project at path (created if missing). Returns files written.
+    Refuses to overwrite anything — init is for new projects, not repair."""
+    root = Path(path)
+    root.mkdir(parents=True, exist_ok=True)
+    project = name or root.resolve().name
+
+    from gitcad.part import Assembly, new_part_id
+
+    root_manifest = Assembly(project).to_manifest(new_part_id())
+    files = {
+        ".gitattributes": _GITATTRIBUTES,
+        ".github/workflows/gitcad.yml": _WORKFLOW,
+        "README.md": _README.format(name=project),
+        f"{project}.gitcad": root_manifest.dumps(),
+        "requirements.reqs": canonical_json(
+            {"schema": "gitcad/requirements@1", "requirements": []},
+            indent=2) + "\n",
+    }
+    existing = [rel for rel in files if (root / rel).exists()]
+    if existing:
+        raise GitcadError(f"refusing to overwrite existing files: {existing} "
+                          "— gitcad init is for new projects")
+
+    written = []
+    for rel, content in files.items():
+        target = root / rel
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(content, encoding="utf-8", newline="\n")
+        written.append(rel)
+
+    if not (root / ".git").exists():
+        subprocess.run(["git", "-C", str(root), "init", "-q"], check=True)
+    # Wire the merge driver into this clone's config (gitattributes names it;
+    # config supplies the command — both halves are needed).
+    subprocess.run(["git", "-C", str(root), "config",
+                    "merge.gitcad.name", "gitcad semantic merge"], check=True)
+    subprocess.run(["git", "-C", str(root), "config",
+                    "merge.gitcad.driver", "gitcad-merge %O %A %B"], check=True)
+    return written
+
+
+def main() -> None:  # pragma: no cover - CLI entrypoint
+    import argparse
+
+    ap = argparse.ArgumentParser(
+        description="gitcad init — scaffold a new project (the repo IS the project)")
+    ap.add_argument("path", nargs="?", default=".")
+    ap.add_argument("--name", help="project name (default: directory name)")
+    args = ap.parse_args()
+    written = init_project(args.path, name=args.name)
+    print("initialized gitcad project:")
+    for rel in written:
+        print(f"  {rel}")
+    print("merge driver wired (merge.gitcad in git config)")

gitcad/lots.py

@@ -0,0 +1,136 @@
+"""Fab-lot traceability — git bisect for hardware bugs.
+
+A lot record binds a PHYSICAL build (fab order, date, vendor) to the exact
+release that produced it: the git commit, the release manifest, and the
+sha256 of every artifact that went to the fab. Years later, "units from
+lot 7" resolves to a commit — and a field failure becomes::
+
+    git bisect start <bad-lot-commit> <good-lot-commit>
+    git bisect run gitcad-verify requirements.json
+
+with the executing requirements suite as the oracle. PLM systems charge
+six figures to approximate this badly; here it is a hash-pinned JSON file
+in the repo.
+
+``verify_lot`` re-hashes the artifacts on disk against the record — a
+swapped Gerber can never silently claim a lot's provenance.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import subprocess
+from pathlib import Path
+
+from gitcad.canonical import canonical_json
+from gitcad.errors import GitcadError
+
+SCHEMA = "gitcad/lot@1"
+
+
+def _sha(path: Path) -> str:
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def _head_commit(repo: Path) -> str:
+    proc = subprocess.run(["git", "-C", str(repo), "rev-parse", "HEAD"],
+                          capture_output=True, text=True)
+    if proc.returncode != 0:
+        raise GitcadError("lot records need a git repo — provenance IS the point")
+    return proc.stdout.strip()
+
+
+def _dirty(repo: Path) -> bool:
+    proc = subprocess.run(["git", "-C", str(repo), "status", "--porcelain"],
+                          capture_output=True, text=True)
+    return bool(proc.stdout.strip())
+
+
+def record_lot(release_dir: str, lot_id: str, *, vendor: str = "",
+               date: str = "", quantity: int | None = None,
+               notes: str = "", repo: str = ".") -> str:
+    """Create ``lot-<id>.json`` next to the release manifest. Refuses a
+    dirty worktree — a lot pinned to a commit that doesn't contain what
+    was actually sent would be provenance theater."""
+    root = Path(repo)
+    rel = Path(release_dir)
+    manifest = rel / "release-manifest.json"
+    if not manifest.is_file():
+        # fall back to any *-manifest.json in the release dir
+        candidates = sorted(rel.glob("*manifest*.json"))
+        if not candidates:
+            raise GitcadError(f"no release manifest found in {release_dir!r}")
+        manifest = candidates[0]
+    if _dirty(root):
+        raise GitcadError(
+            "worktree is dirty — commit first; a lot must pin a commit that "
+            "contains exactly what was sent to the fab")
+
+    artifacts = {p.name: _sha(p) for p in sorted(rel.iterdir())
+                 if p.is_file() and p.suffix != ".lot"
+                 and not p.name.startswith("lot-")}
+    doc = {"schema": SCHEMA, "lot": {
+        "id": lot_id, "vendor": vendor, "date": date,
+        **({"quantity": quantity} if quantity is not None else {}),
+        **({"notes": notes} if notes else {}),
+        "commit": _head_commit(root),
+        "manifest": manifest.name,
+        "artifacts": artifacts,
+    }}
+    out = rel / f"{lot_id}.lot"
+    if out.exists():
+        raise GitcadError(f"lot {lot_id!r} already recorded — lots are immutable; "
+                          "record a new lot id for a re-run")
+    out.write_text(canonical_json(doc, indent=2) + "\n", encoding="utf-8")
+    return str(out)
+
+
+def verify_lot(lot_path: str) -> dict:
+    """Re-hash the artifacts against the lot record. Any mismatch is named —
+    a swapped file can never silently claim this lot's provenance."""
+    p = Path(lot_path)
+    doc = json.loads(p.read_text(encoding="utf-8"))
+    if doc.get("schema") != SCHEMA:
+        raise GitcadError(f"unsupported lot schema {doc.get('schema')!r}")
+    lot = doc["lot"]
+    mismatches: list[str] = []
+    missing: list[str] = []
+    for name, want in sorted(lot["artifacts"].items()):
+        f = p.parent / name
+        if not f.is_file():
+            missing.append(name)
+        elif _sha(f) != want:
+            mismatches.append(name)
+    ok = not (mismatches or missing)
+    return {"ok": ok, "lot": lot["id"], "commit": lot["commit"],
+            "artifacts": len(lot["artifacts"]),
+            "mismatched": mismatches, "missing": missing}
+
+
+def main() -> None:  # pragma: no cover - CLI entrypoint
+    import argparse
+    import sys
+
+    ap = argparse.ArgumentParser(description="gitcad lots — fab-lot provenance")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    rec = sub.add_parser("record", help="record a lot against a release dir")
+    rec.add_argument("release_dir")
+    rec.add_argument("lot_id")
+    rec.add_argument("--vendor", default="")
+    rec.add_argument("--date", default="")
+    rec.add_argument("--quantity", type=int)
+    rec.add_argument("--notes", default="")
+    rec.add_argument("--repo", default=".")
+    ver = sub.add_parser("verify", help="re-hash artifacts against a lot record")
+    ver.add_argument("lot_file")
+    args = ap.parse_args()
+    if args.cmd == "record":
+        path = record_lot(args.release_dir, args.lot_id, vendor=args.vendor,
+                          date=args.date, quantity=args.quantity,
+                          notes=args.notes, repo=args.repo)
+        print(f"recorded {path}")
+    else:
+        r = verify_lot(args.lot_file)
+        print(json.dumps(r, indent=2))
+        sys.exit(0 if r["ok"] else 1)

gitcad/mcp/__init__.py

@@ -0,0 +1,15 @@
+"""The MCP surface — gitcad's PRIMARY interface.
+
+Design rule (ADR-0002): the MCP tool surface is designed first and the Python
+API is a thin binding over the same handlers, not the reverse. If MCP is the
+primary interface it never rots, because it is the interface everything (agents,
+the web UI, humans) actually uses.
+
+:mod:`gitcad.mcp.server` defines the tool handlers as plain, importable
+functions (a registry) so they are unit-testable with no ``mcp`` dependency, and
+wraps them as MCP tools only when the optional ``mcp`` package is present.
+"""
+
+from gitcad.mcp.server import REGISTRY, main
+
+__all__ = ["REGISTRY", "main"]