Runs live, versioned Python application objects on one VM, with a suite of apps: projects, notes, tasks, files and more.

0 downloads

dbbasic-object-server/tests/test_object_packages.py
Download zip
Clone
Clone with git
git clone https://gitstable.com/git/askrobots/dbbasic-object-server.git
HTTPS
https://gitstable.com/git/askrobots/dbbasic-object-server.git
SSH
ssh://git@gitstable.com:2222/askrobots/dbbasic-object-server.git

Cloning needs no sign-in. Pushing over HTTPS asks for your username and an access token. SSH needs your key under SSH keys.

danq9 signup: the person chooses the password and name on the confirm page 83c7aa6 2 weeks, 5 days ago History
test_object_packages.py · 59.1 KB · 1599 lines
1import json
2from pathlib import Path
3
4import pytest
5
6import object_execution
7import object_namespace
8import object_package_baselines
9import object_packages
10import object_reconciles
11import object_record_changes
12import object_records
13import object_schemas
14import object_state
15import python_object_runtime
16
17
18def write_package(root, package_id, payload, files=()):
19 package_dir = root / package_id
20 package_dir.mkdir(parents=True)
21 (package_dir / object_packages.MANIFEST_FILE).write_text(json.dumps(payload))
22 for relative_path, content in files:
23 path = package_dir / relative_path
24 path.parent.mkdir(parents=True, exist_ok=True)
25 path.write_text(content)
26 return package_dir
27
28
29def update_package(root, package_id, payload, files=()):
30 """Overwrite an already-written package's manifest and files (a "new version")."""
31 package_dir = root / package_id
32 (package_dir / object_packages.MANIFEST_FILE).write_text(json.dumps(payload))
33 for relative_path, content in files:
34 path = package_dir / relative_path
35 path.parent.mkdir(parents=True, exist_ok=True)
36 path.write_text(content)
37 return package_dir
38
39
40def _reconcile_manifest(version):
41 return {
42 "id": "hello-world",
43 "name": "Hello World",
44 "version": version,
45 "objects": [{"id": "hello_world", "path": "objects/hello/world.py"}],
46 "schemas": [{"collection": "contacts", "path": "schemas/contacts.json"}],
47 }
48
49
50def _install_reconcile_fixture(tmp_path, *, edit_object=False, edit_schema=False):
51 """Install hello-world v0.1.0, optionally customize the live object/schema."""
52 packages_root = tmp_path / "packages"
53 data_dir = tmp_path / "data"
54 object_root = tmp_path / "objects"
55 object_root.mkdir()
56
57 write_package(
58 packages_root,
59 "hello-world",
60 _reconcile_manifest("0.1.0"),
61 files=(
62 ("objects/hello/world.py", "def GET(request): return {'v': 1}\n"),
63 (
64 "schemas/contacts.json",
65 json.dumps({"name": "contacts", "fields": [{"name": "id", "type": "text"}]}),
66 ),
67 ),
68 )
69 object_packages.install_package(
70 "hello-world",
71 root=packages_root,
72 base_dir=data_dir,
73 object_roots=[object_root],
74 )
75
76 if edit_object:
77 (object_root / "hello" / "world.py").write_text("def GET(request): return {'v': 'customized'}\n")
78 if edit_schema:
79 # Change "id"'s type (diverging from the shipped base) as well as
80 # adding a new field, so a later package change to "id" is a real
81 # field-level collision rather than a union-mergeable diff.
82 object_schemas.replace_schema(
83 "contacts",
84 {
85 "name": "contacts",
86 "fields": [
87 {"name": "id", "type": "number"},
88 {"name": "x_priority", "type": "text"},
89 ],
90 },
91 base_dir=data_dir,
92 )
93
94 return packages_root, data_dir, object_root
95
96
97def _bump_reconcile_package(packages_root, *, version, object_code=None, schema_fields=None):
98 package_dir = packages_root / "hello-world"
99 files = []
100 if object_code is not None:
101 files.append(("objects/hello/world.py", object_code))
102 if schema_fields is not None:
103 files.append(("schemas/contacts.json", json.dumps({"name": "contacts", "fields": schema_fields})))
104 update_package(packages_root, "hello-world", _reconcile_manifest(version), files=files)
105
106
107def manifest(package_id="crm-starter", **overrides):
108 payload = {
109 "id": package_id,
110 "name": "CRM Starter",
111 "version": "0.1.0",
112 "description": "Contacts and deals",
113 "compatibility": {"object_server": ">=0.0.1"},
114 "dependencies": [{"id": "hello-world", "version": ">=0.1.0"}],
115 "objects": [{"id": "crm_contacts", "path": "objects/crm/contacts.py"}],
116 "schemas": [{"collection": "contacts", "path": "schemas/contacts.json"}],
117 "permissions": [{"path": "permissions/policy.json"}],
118 "seed": [{"collection": "contacts", "path": "seed/contacts.tsv"}],
119 "migrations": [{"id": "001_init", "path": "migrations/001_init.py"}],
120 }
121 payload.update(overrides)
122 return payload
123
124
125def test_list_packages_returns_manifest_summaries(tmp_path):
126 packages_root = tmp_path / "packages"
127 write_package(packages_root, "hello-world", manifest("hello-world"))
128 write_package(packages_root, "crm-starter", manifest("crm-starter"))
129 write_package(packages_root, "Bad.Name", manifest("Bad.Name"))
130
131 packages = object_packages.list_packages(root=packages_root)
132
133 assert [package["id"] for package in packages] == ["crm-starter", "hello-world"]
134 assert packages[0]["status"] == "available"
135 assert packages[0]["object_count"] == 1
136 assert packages[0]["schema_count"] == 1
137 assert packages[0]["dependency_count"] == 1
138
139
140def test_get_package_normalizes_manifest(tmp_path):
141 packages_root = tmp_path / "packages"
142 write_package(packages_root, "crm-starter", manifest())
143
144 package = object_packages.get_package("crm-starter", root=packages_root)
145
146 assert package["id"] == "crm-starter"
147 assert package["objects"] == [{"id": "crm_contacts", "path": "objects/crm/contacts.py"}]
148 assert package["schemas"] == [{"collection": "contacts", "path": "schemas/contacts.json"}]
149 assert package["dependencies"] == [{"id": "hello-world", "version": ">=0.1.0"}]
150
151
152def test_dry_run_reports_create_replace_merge_apply_and_missing_files(tmp_path):
153 packages_root = tmp_path / "packages"
154 data_dir = tmp_path / "data"
155 object_root = tmp_path / "objects"
156 (object_root / "crm").mkdir(parents=True)
157 (object_root / "crm" / "contacts.py").write_text("def GET(request): return {}\n")
158 (data_dir / "schemas").mkdir(parents=True)
159 (data_dir / "schemas" / "contacts.json").write_text('{"fields":[]}\n')
160 (data_dir / "collections" / "contacts").mkdir(parents=True)
161 (data_dir / "collections" / "contacts" / "records.tsv").write_text("id\tname\nc1\tAlice\n")
162 (data_dir / object_packages.PACKAGE_MIGRATIONS_DIR / "crm-starter").mkdir(parents=True)
163 (data_dir / object_packages.PACKAGE_MIGRATIONS_DIR / "crm-starter" / "001_init.json").write_text("{}\n")
164
165 write_package(
166 packages_root,
167 "crm-starter",
168 manifest(),
169 files=(
170 ("objects/crm/contacts.py", "def GET(request): return {}\n"),
171 ("schemas/contacts.json", '{"fields":[]}\n'),
172 ("permissions/policy.json", '{"rules": []}\n'),
173 ("seed/contacts.tsv", "id\tname\nc2\tBob\n"),
174 ),
175 )
176
177 plan = object_packages.dry_run_package(
178 "crm-starter",
179 root=packages_root,
180 base_dir=data_dir,
181 object_roots=[object_root],
182 )
183
184 assert plan["mode"] == "dry_run"
185 assert plan["install_enabled"] is False
186 assert plan["safe_to_install"] is False
187 assert plan["objects"][0]["action"] == "replace"
188 assert plan["schemas"][0]["action"] == "replace"
189 assert plan["permissions"][0]["action"] == "merge"
190 assert plan["seed"][0]["action"] == "skip"
191 assert plan["migrations"][0]["action"] == "skip"
192 assert plan["warnings"] == ["Missing package migration file: migrations/001_init.py"]
193
194
195def test_dry_run_is_safe_when_declared_files_exist(tmp_path):
196 packages_root = tmp_path / "packages"
197 write_package(
198 packages_root,
199 "hello-world",
200 {
201 "id": "hello-world",
202 "name": "Hello World",
203 "version": "0.1.0",
204 "objects": [{"id": "hello_world", "path": "objects/hello/world.py"}],
205 },
206 files=(("objects/hello/world.py", "def GET(request): return {}\n"),),
207 )
208
209 plan = object_packages.dry_run_package("hello-world", root=packages_root)
210
211 assert plan["safe_to_install"] is True
212 assert plan["warnings"] == []
213 assert plan["objects"][0]["action"] == "create"
214
215
216def test_repository_system_dashboard_package_installs_and_executes(tmp_path):
217 packages_root = Path("packages")
218 data_dir = tmp_path / "data"
219 object_root = tmp_path / "objects"
220
221 package = object_packages.get_package("system-dashboard", root=packages_root)
222 plan = object_packages.dry_run_package(
223 "system-dashboard",
224 root=packages_root,
225 base_dir=data_dir,
226 object_roots=[object_root],
227 )
228
229 # 0.6.0 added the scheduler board alongside the dashboard page.
230 assert package["objects"] == [
231 {"id": "system_dashboard", "path": "objects/system/dashboard.py"},
232 {"id": "system_scheduler", "path": "objects/system/scheduler.py"},
233 # 0.8.0: failed scheduled runs, the one `urgent` attention
234 # provider on this server.
235 {"id": "system_scheduler_attention",
236 "path": "objects/system/scheduler_attention.py"},
237 ]
238 assert plan["safe_to_install"] is True
239 assert plan["objects"][0]["action"] == "create"
240
241 install = object_packages.install_package(
242 "system-dashboard",
243 root=packages_root,
244 base_dir=data_dir,
245 object_roots=[object_root],
246 )
247
248 assert install["objects"][0]["destination"] == "system/dashboard.py"
249 assert (object_root / "system" / "dashboard.py").is_file()
250
251 runtime = python_object_runtime.PythonObjectRuntime(base_dir=data_dir)
252 result = object_execution.execute_object(
253 runtime,
254 object_execution.ObjectExecutionRequest("system_dashboard"),
255 roots=[object_root],
256 )
257
258 assert result.ok is True
259 assert result.result["content_type"] == "text/html; charset=utf-8"
260 assert "DBBASIC Dashboard" in result.result["body"]
261 assert "sign in</a> for live metrics" in result.result["body"]
262 assert object_state.get_object_state("system_dashboard", base_dir=data_dir)["served"] == 1
263
264
265def test_repository_admin_write_probe_package_installs_and_writes_records(tmp_path):
266 packages_root = Path("packages")
267 data_dir = tmp_path / "data"
268 object_root = tmp_path / "objects"
269
270 package = object_packages.get_package("admin-write-probe", root=packages_root)
271 plan = object_packages.dry_run_package(
272 "admin-write-probe",
273 root=packages_root,
274 base_dir=data_dir,
275 object_roots=[object_root],
276 )
277
278 assert package["objects"] == [
279 {"id": "system_write_probe", "path": "objects/system/write_probe.py"}
280 ]
281 assert package["schemas"] == [
282 {"collection": "dbbasic_probe", "path": "schemas/dbbasic_probe.json"}
283 ]
284 assert package["seed"] == [
285 {"collection": "dbbasic_probe", "path": "seed/dbbasic_probe.tsv"}
286 ]
287 assert plan["safe_to_install"] is True
288 assert plan["objects"][0]["action"] == "create"
289 assert plan["schemas"][0]["action"] == "create"
290 assert plan["seed"][0]["action"] == "create"
291
292 install = object_packages.install_package(
293 "admin-write-probe",
294 root=packages_root,
295 base_dir=data_dir,
296 object_roots=[object_root],
297 )
298
299 assert install["objects"][0]["destination"] == "system/write_probe.py"
300 assert install["schemas"][0]["destination"] == "schemas/dbbasic_probe.json"
301 assert install["seed"][0]["destination"] == "collections/dbbasic_probe/records.tsv"
302 assert (object_root / "system" / "write_probe.py").is_file()
303
304 runtime = python_object_runtime.PythonObjectRuntime(base_dir=data_dir)
305 result = object_execution.execute_object(
306 runtime,
307 object_execution.ObjectExecutionRequest("system_write_probe"),
308 roots=[object_root],
309 )
310
311 assert result.ok is True
312 assert result.result["content_type"] == "text/html; charset=utf-8"
313 assert "DBBASIC Write Probe" in result.result["body"]
314 assert "packages/admin-write-probe" in result.result["body"]
315 assert object_state.get_object_state("system_write_probe", base_dir=data_dir)["served"] == 1
316
317 record = object_records.create_collection_record(
318 "dbbasic_probe",
319 {
320 "id": "probe_test",
321 "note": "created by package test",
322 "status": "created",
323 "updated_at": "2026-07-01T00:00:00+00:00",
324 },
325 base_dir=data_dir,
326 )
327 assert record["status"] == "created"
328
329 updated = object_records.update_collection_record(
330 "dbbasic_probe",
331 "probe_test",
332 {
333 "note": "updated by package test",
334 "status": "updated",
335 },
336 base_dir=data_dir,
337 )
338 assert updated["note"] == "updated by package test"
339 assert updated["status"] == "updated"
340
341 deleted = object_records.delete_collection_record(
342 "dbbasic_probe",
343 "probe_test",
344 base_dir=data_dir,
345 )
346 assert deleted["id"] == "probe_test"
347 assert object_records.read_collection_records("dbbasic_probe", base_dir=data_dir) == []
348
349
350def test_install_package_creates_objects_schemas_and_seed(tmp_path):
351 packages_root = tmp_path / "packages"
352 data_dir = tmp_path / "data"
353 object_root = tmp_path / "objects"
354 write_package(
355 packages_root,
356 "hello-world",
357 {
358 "id": "hello-world",
359 "name": "Hello World",
360 "version": "0.1.0",
361 "objects": [{"id": "hello_world", "path": "objects/hello/world.py"}],
362 "schemas": [{"collection": "contacts", "path": "schemas/contacts.json"}],
363 "permissions": [],
364 "seed": [{"collection": "contacts", "path": "seed/contacts.tsv"}],
365 "migrations": [],
366 },
367 files=(
368 ("objects/hello/world.py", "def GET(request): return {'status': 'ok'}\n"),
369 ("schemas/contacts.json", '{"name":"contacts","fields":[{"name":"id","type":"text"}]}\n'),
370 ("seed/contacts.tsv", "id\tname\nc1\tAlice\n"),
371 ),
372 )
373
374 result = object_packages.install_package(
375 "hello-world",
376 root=packages_root,
377 base_dir=data_dir,
378 object_roots=[object_root],
379 )
380
381 assert result["mode"] == "install"
382 assert result["install_enabled"] is True
383 assert result["objects"][0]["destination"] == "hello/world.py"
384 assert (object_root / "hello" / "world.py").read_text() == "def GET(request): return {'status': 'ok'}\n"
385 schema = json.loads((data_dir / "schemas" / "contacts.json").read_text())
386 assert schema["name"] == "contacts"
387 assert schema["field_count"] == 1
388 assert (data_dir / "collections" / "contacts" / "records.tsv").read_text() == "id\tname\nc1\tAlice\n"
389
390
391def test_install_package_attributes_seed_records(tmp_path):
392 """Seed writes bypass object_records.create_collection_record (the whole
393
394 records.tsv lands as one atomic byte copy), so unlike a normal record
395 write nothing emits a change automatically -- universal attribution
396 still requires one, attributed to the installing package.
397 """
398 packages_root = tmp_path / "packages"
399 data_dir = tmp_path / "data"
400 object_root = tmp_path / "objects"
401 write_package(
402 packages_root,
403 "hello-world",
404 {
405 "id": "hello-world",
406 "name": "Hello World",
407 "version": "0.1.0",
408 "objects": [],
409 "schemas": [{"collection": "contacts", "path": "schemas/contacts.json"}],
410 "permissions": [],
411 "seed": [{"collection": "contacts", "path": "seed/contacts.tsv"}],
412 "migrations": [],
413 },
414 files=(
415 ("schemas/contacts.json", '{"name":"contacts","fields":[{"name":"id","type":"text"}]}\n'),
416 ("seed/contacts.tsv", "id\tname\nc1\tAlice\nc2\tBob\n"),
417 ),
418 )
419
420 object_packages.install_package(
421 "hello-world",
422 root=packages_root,
423 base_dir=data_dir,
424 object_roots=[object_root],
425 )
426
427 changes = object_record_changes.list_record_changes("contacts", base_dir=data_dir)["changes"]
428 assert {change["record_id"] for change in changes} == {"c1", "c2"}
429 assert all(change["action"] == "create" for change in changes)
430 assert all(change["actor"] == "package-install:hello-world" for change in changes)
431
432
433def test_install_package_refuses_existing_objects_without_replace(tmp_path):
434 packages_root = tmp_path / "packages"
435 object_root = tmp_path / "objects"
436 (object_root / "hello").mkdir(parents=True)
437 (object_root / "hello" / "world.py").write_text("def GET(request): return {'old': True}\n")
438 write_package(
439 packages_root,
440 "hello-world",
441 {
442 "id": "hello-world",
443 "name": "Hello World",
444 "version": "0.1.0",
445 "objects": [{"id": "hello_world", "path": "objects/hello/world.py"}],
446 },
447 files=(("objects/hello/world.py", "def GET(request): return {'new': True}\n"),),
448 )
449
450 with pytest.raises(object_packages.PackageInstallError, match="allow_replace=true"):
451 object_packages.install_package(
452 "hello-world",
453 root=packages_root,
454 object_roots=[object_root],
455 )
456
457 assert (object_root / "hello" / "world.py").read_text() == "def GET(request): return {'old': True}\n"
458
459
460def test_install_package_replaces_objects_when_allowed(tmp_path):
461 # The pre-existing file here was never installed by this package (no
462 # baseline recorded for it), so the reconcile engine has no basis to call
463 # it "pristine" and would park it as a conflict rather than guess. This
464 # is the "replaces when allowed" path re-armed under Phase 2: allow_replace
465 # clears the create/replace blocker, and force is the explicit "discard
466 # whatever is there" signal (see docs/upgrade-and-customization.md Rule 1).
467 packages_root = tmp_path / "packages"
468 object_root = tmp_path / "objects"
469 (object_root / "hello").mkdir(parents=True)
470 (object_root / "hello" / "world.py").write_text("def GET(request): return {'old': True}\n")
471 write_package(
472 packages_root,
473 "hello-world",
474 {
475 "id": "hello-world",
476 "name": "Hello World",
477 "version": "0.1.0",
478 "objects": [{"id": "hello_world", "path": "objects/hello/world.py"}],
479 },
480 files=(("objects/hello/world.py", "def GET(request): return {'new': True}\n"),),
481 )
482
483 result = object_packages.install_package(
484 "hello-world",
485 root=packages_root,
486 base_dir=tmp_path / "data",
487 object_roots=[object_root],
488 allow_replace=True,
489 force=True,
490 )
491
492 assert result["objects"][0]["action"] == "replace"
493 assert result["objects"][0]["status"] == "forced"
494 assert (object_root / "hello" / "world.py").read_text() == "def GET(request): return {'new': True}\n"
495
496
497def test_install_package_parks_conflict_when_replace_has_no_baseline(tmp_path):
498 # Same setup as above, but WITHOUT force: an untracked existing file plus
499 # differing shipped content is a conflict, not a blind overwrite. The
500 # install still succeeds; the live file is left untouched and a
501 # pending-reconcile record is created instead.
502 packages_root = tmp_path / "packages"
503 object_root = tmp_path / "objects"
504 (object_root / "hello").mkdir(parents=True)
505 (object_root / "hello" / "world.py").write_text("def GET(request): return {'old': True}\n")
506 write_package(
507 packages_root,
508 "hello-world",
509 {
510 "id": "hello-world",
511 "name": "Hello World",
512 "version": "0.1.0",
513 "objects": [{"id": "hello_world", "path": "objects/hello/world.py"}],
514 },
515 files=(("objects/hello/world.py", "def GET(request): return {'new': True}\n"),),
516 )
517
518 result = object_packages.install_package(
519 "hello-world",
520 root=packages_root,
521 base_dir=tmp_path / "data",
522 object_roots=[object_root],
523 allow_replace=True,
524 )
525
526 assert result["objects"][0]["action"] == "replace"
527 assert result["objects"][0]["status"] == "conflict"
528 assert "reconcile_id" in result["objects"][0]
529 assert result["reconciles"] == [result["objects"][0]["reconcile_id"]]
530 assert (object_root / "hello" / "world.py").read_text() == "def GET(request): return {'old': True}\n"
531
532
533def test_install_package_runs_before_write_hook_after_validation(tmp_path):
534 packages_root = tmp_path / "packages"
535 object_root = tmp_path / "objects"
536 write_package(
537 packages_root,
538 "hello-world",
539 {
540 "id": "hello-world",
541 "name": "Hello World",
542 "version": "0.1.0",
543 "objects": [{"id": "hello_world", "path": "objects/hello/world.py"}],
544 },
545 files=(("objects/hello/world.py", "def GET(request): return {'new': True}\n"),),
546 )
547 calls = []
548
549 def before_write(plan):
550 calls.append(plan["package"]["id"])
551 assert not (object_root / "hello" / "world.py").exists()
552 return {"path": "restore-point.tar.gz"}
553
554 result = object_packages.install_package(
555 "hello-world",
556 root=packages_root,
557 object_roots=[object_root],
558 before_write=before_write,
559 )
560
561 assert calls == ["hello-world"]
562 assert result["restore_point"] == {"path": "restore-point.tar.gz"}
563 assert (object_root / "hello" / "world.py").is_file()
564
565
566def test_install_package_does_not_run_before_write_hook_when_blocked(tmp_path):
567 packages_root = tmp_path / "packages"
568 object_root = tmp_path / "objects"
569 (object_root / "hello").mkdir(parents=True)
570 (object_root / "hello" / "world.py").write_text("def GET(request): return {'old': True}\n")
571 write_package(
572 packages_root,
573 "hello-world",
574 {
575 "id": "hello-world",
576 "name": "Hello World",
577 "version": "0.1.0",
578 "objects": [{"id": "hello_world", "path": "objects/hello/world.py"}],
579 },
580 files=(("objects/hello/world.py", "def GET(request): return {'new': True}\n"),),
581 )
582 calls = []
583
584 with pytest.raises(object_packages.PackageInstallError):
585 object_packages.install_package(
586 "hello-world",
587 root=packages_root,
588 object_roots=[object_root],
589 before_write=lambda plan: calls.append(plan["package"]["id"]),
590 )
591
592 assert calls == []
593 assert (object_root / "hello" / "world.py").read_text() == "def GET(request): return {'old': True}\n"
594
595
596def test_install_package_rejects_unsupported_permission_and_migration_writes(tmp_path):
597 packages_root = tmp_path / "packages"
598 write_package(
599 packages_root,
600 "crm-starter",
601 manifest(),
602 files=(
603 ("objects/crm/contacts.py", "def GET(request): return {}\n"),
604 ("schemas/contacts.json", '{"fields":[]}\n'),
605 ("permissions/policy.json", '{"rules": []}\n'),
606 ("seed/contacts.tsv", "id\tname\nc2\tBob\n"),
607 ("migrations/001_init.py", "def run(): pass\n"),
608 ),
609 )
610
611 with pytest.raises(object_packages.PackageInstallError) as exc:
612 object_packages.install_package("crm-starter", root=packages_root)
613
614 assert "migration execution" in str(exc.value)
615
616
617def test_install_package_merges_permission_rules_with_provenance(tmp_path):
618 import object_permission_store
619
620 packages_root = tmp_path / "packages"
621 data_dir = tmp_path / "data"
622 object_root = tmp_path / "objects"
623 object_root.mkdir()
624 fragment = json.dumps(
625 {
626 "rules": [
627 {
628 "effect": "allow",
629 "principal": "public",
630 "actions": ["execute"],
631 "object_id": "crm_contacts",
632 "reason": "public contacts page",
633 },
634 {
635 "effect": "allow",
636 "principal": "registered",
637 "actions": ["read", "create"],
638 "collection": "contacts",
639 },
640 ]
641 }
642 )
643 payload = manifest(dependencies=[], migrations=[], seed=[])
644 write_package(
645 packages_root,
646 "crm-starter",
647 payload,
648 files=(
649 ("objects/crm/contacts.py", "def GET(request): return {}\n"),
650 ("schemas/contacts.json", '{"fields":[]}\n'),
651 ("permissions/policy.json", fragment),
652 ),
653 )
654
655 plan = object_packages.dry_run_package(
656 "crm-starter", root=packages_root, base_dir=data_dir, object_roots=[object_root]
657 )
658 install = object_packages.install_package(
659 "crm-starter", root=packages_root, base_dir=data_dir, object_roots=[object_root]
660 )
661 policy = object_permission_store.load_policy(data_dir)
662
663 assert plan["permissions"][0] == {
664 "path": "permissions/policy.json",
665 "action": "merge",
666 "exists": True,
667 "rules": 2,
668 "new_rules": 2,
669 }
670 assert install["permissions"][0]["status"] == "merged"
671 assert install["permissions"][0]["new_rules"] == 2
672 assert len(policy.rules) == 2
673 assert all(rule.package == "crm-starter" for rule in policy.rules)
674 assert policy.rules[0].object_id == "crm_contacts"
675
676 reinstall = object_packages.install_package(
677 "crm-starter",
678 root=packages_root,
679 base_dir=data_dir,
680 object_roots=[object_root],
681 allow_replace=True,
682 )
683 policy_after = object_permission_store.load_policy(data_dir)
684
685 assert reinstall["permissions"][0]["new_rules"] == 0
686 assert len(policy_after.rules) == 2
687
688
689def test_install_package_rejects_invalid_permission_fragment(tmp_path):
690 packages_root = tmp_path / "packages"
691 object_root = tmp_path / "objects"
692 object_root.mkdir()
693 payload = manifest(dependencies=[], migrations=[], schemas=[], seed=[])
694 write_package(
695 packages_root,
696 "crm-starter",
697 payload,
698 files=(
699 ("objects/crm/contacts.py", "def GET(request): return {}\n"),
700 ("permissions/policy.json", '{"rules": [{"effect": "allow"}]}\n'),
701 ),
702 )
703
704 with pytest.raises(object_packages.PackageInstallError) as exc:
705 object_packages.install_package(
706 "crm-starter",
707 root=packages_root,
708 base_dir=tmp_path / "data",
709 object_roots=[object_root],
710 )
711
712 assert "permission rule is invalid" in str(exc.value)
713
714
715def test_install_package_merges_seed_by_id_preserving_existing(tmp_path):
716 # Seeding a collection that already holds records MERGES by id: existing
717 # rows survive untouched, and seed rows whose id isn't present are added.
718 # This is what lets several packages each seed a shared collection
719 # (views/site_routes) and lets a new package version ship new default rows,
720 # while never clobbering live data ("upgrade the app, keep the data").
721 packages_root = tmp_path / "packages"
722 data_dir = tmp_path / "data"
723 (data_dir / "collections" / "contacts").mkdir(parents=True)
724 (data_dir / "collections" / "contacts" / "records.tsv").write_text("id\tname\nc1\tAlice\n")
725 write_package(
726 packages_root,
727 "seeded",
728 {
729 "id": "seeded",
730 "name": "Seeded",
731 "version": "0.1.0",
732 "seed": [{"collection": "contacts", "path": "seed/contacts.tsv"}],
733 },
734 files=(("seed/contacts.tsv", "id\tname\nc2\tBob\n"),),
735 )
736
737 result = object_packages.install_package(
738 "seeded", root=packages_root, base_dir=data_dir, allow_replace=True
739 )
740
741 seed_entry = result["seed"][0]
742 assert seed_entry["status"] == "merged"
743 assert seed_entry["installed"] is True
744 assert seed_entry["added"] == 1
745 # Existing row (Alice) preserved AND the new seed row (Bob) merged in by id.
746 records = object_records.read_collection_records("contacts", base_dir=data_dir)
747 assert {r["name"] for r in records} == {"Alice", "Bob"}
748 # Re-installing adds nothing (ids already present).
749 again = object_packages.install_package(
750 "seeded", root=packages_root, base_dir=data_dir, allow_replace=True
751 )
752 assert again["seed"][0]["status"] == "skipped" and again["seed"][0]["added"] == 0
753
754
755def test_install_package_validates_schema_before_writing_objects(tmp_path):
756 packages_root = tmp_path / "packages"
757 data_dir = tmp_path / "data"
758 object_root = tmp_path / "objects"
759 write_package(
760 packages_root,
761 "bad-schema",
762 {
763 "id": "bad-schema",
764 "name": "Bad Schema",
765 "version": "0.1.0",
766 "objects": [{"id": "hello_world", "path": "objects/hello/world.py"}],
767 "schemas": [{"collection": "contacts", "path": "schemas/contacts.json"}],
768 },
769 files=(
770 ("objects/hello/world.py", "def GET(request): return {'status': 'ok'}\n"),
771 ("schemas/contacts.json", '{"name":"other","fields":[]}\n'),
772 ),
773 )
774
775 with pytest.raises(object_packages.PackageInstallError, match="schema is invalid"):
776 object_packages.install_package(
777 "bad-schema",
778 root=packages_root,
779 base_dir=data_dir,
780 object_roots=[object_root],
781 )
782
783 assert not (object_root / "hello" / "world.py").exists()
784
785
786def test_package_manifest_rejects_unsafe_paths_and_ids(tmp_path):
787 packages_root = tmp_path / "packages"
788 write_package(
789 packages_root,
790 "bad-package",
791 manifest("bad-package", objects=[{"id": "bad/id", "path": "../secret.py"}]),
792 )
793
794 with pytest.raises(object_packages.InvalidPackageManifestError):
795 object_packages.get_package("bad-package", root=packages_root)
796
797 with pytest.raises(object_packages.InvalidPackageIdError):
798 object_packages.get_package("../bad", root=packages_root)
799
800
801def test_missing_package_raises(tmp_path):
802 with pytest.raises(object_packages.PackageNotFoundError):
803 object_packages.get_package("missing", root=tmp_path / "packages")
804
805
806# --- Phase 2: reconcile-on-upgrade decision table ---------------------------
807#
808# See docs/upgrade-and-customization.md (Rule 1). Each test below exercises
809# one row of the three-way-compare table for objects (and, at the end,
810# schemas): pristine vs customized, shipped unchanged vs shipped changed.
811
812
813def test_reconcile_fresh_install_status_written(tmp_path):
814 packages_root = tmp_path / "packages"
815 data_dir = tmp_path / "data"
816 object_root = tmp_path / "objects"
817 object_root.mkdir()
818 write_package(
819 packages_root,
820 "hello-world",
821 _reconcile_manifest("0.1.0"),
822 files=(
823 ("objects/hello/world.py", "def GET(request): return {'v': 1}\n"),
824 (
825 "schemas/contacts.json",
826 json.dumps({"name": "contacts", "fields": [{"name": "id", "type": "text"}]}),
827 ),
828 ),
829 )
830
831 result = object_packages.install_package(
832 "hello-world",
833 root=packages_root,
834 base_dir=data_dir,
835 object_roots=[object_root],
836 )
837
838 assert result["objects"][0]["status"] == "written"
839 assert result["schemas"][0]["status"] == "written"
840 assert result["reconciles"] == []
841
842
843def test_reconcile_unchanged_reinstall_is_noop(tmp_path):
844 packages_root, data_dir, object_root = _install_reconcile_fixture(tmp_path)
845
846 result = object_packages.install_package(
847 "hello-world",
848 root=packages_root,
849 base_dir=data_dir,
850 object_roots=[object_root],
851 allow_replace=True,
852 )
853
854 assert result["objects"][0]["status"] == "unchanged"
855 assert result["schemas"][0]["status"] == "unchanged"
856 assert result["reconciles"] == []
857 assert (object_root / "hello" / "world.py").read_text() == "def GET(request): return {'v': 1}\n"
858
859
860def test_reconcile_pristine_fast_forwards_on_upgrade(tmp_path):
861 packages_root, data_dir, object_root = _install_reconcile_fixture(tmp_path, edit_object=False)
862 _bump_reconcile_package(
863 packages_root,
864 version="0.2.0",
865 object_code="def GET(request): return {'v': 2}\n",
866 )
867
868 result = object_packages.install_package(
869 "hello-world",
870 root=packages_root,
871 base_dir=data_dir,
872 object_roots=[object_root],
873 allow_replace=True,
874 )
875
876 assert result["objects"][0]["status"] == "updated"
877 assert result["reconciles"] == []
878 assert (object_root / "hello" / "world.py").read_text() == "def GET(request): return {'v': 2}\n"
879
880 baseline = object_package_baselines.load_baseline("hello-world", base_dir=data_dir)
881 assert baseline["version"] == "0.2.0"
882 assert baseline["objects"]["hello_world"] == object_package_baselines.sha256_text(
883 "def GET(request): return {'v': 2}\n"
884 )
885
886
887def test_reconcile_customized_and_shipped_unchanged_keeps_customization(tmp_path):
888 packages_root, data_dir, object_root = _install_reconcile_fixture(tmp_path, edit_object=True)
889
890 result = object_packages.install_package(
891 "hello-world",
892 root=packages_root,
893 base_dir=data_dir,
894 object_roots=[object_root],
895 allow_replace=True,
896 )
897
898 assert result["objects"][0]["status"] == "kept"
899 assert result["reconciles"] == []
900 assert (
901 object_root / "hello" / "world.py"
902 ).read_text() == "def GET(request): return {'v': 'customized'}\n"
903
904
905def test_reconcile_customized_and_shipped_changed_parks_conflict(tmp_path):
906 packages_root, data_dir, object_root = _install_reconcile_fixture(tmp_path, edit_object=True)
907 _bump_reconcile_package(
908 packages_root,
909 version="0.2.0",
910 object_code="def GET(request): return {'v': 2}\n",
911 )
912
913 result = object_packages.install_package(
914 "hello-world",
915 root=packages_root,
916 base_dir=data_dir,
917 object_roots=[object_root],
918 allow_replace=True,
919 )
920
921 assert result["objects"][0]["status"] == "conflict"
922 assert "reconcile_id" in result["objects"][0]
923 assert result["reconciles"] == [result["objects"][0]["reconcile_id"]]
924 # The install itself never raises: the conflict is parked, not blocking.
925 assert (
926 object_root / "hello" / "world.py"
927 ).read_text() == "def GET(request): return {'v': 'customized'}\n"
928
929 reconcile = object_reconciles.get_reconcile(result["objects"][0]["reconcile_id"], base_dir=data_dir)
930 assert reconcile["status"] == "pending"
931 assert reconcile["package"] == "hello-world"
932 assert reconcile["target_version"] == "0.2.0"
933 assert reconcile["baseline_version"] == "0.1.0"
934 assert reconcile["artifact"] == {"kind": "object", "id": "hello_world"}
935 assert reconcile["mine"] == "def GET(request): return {'v': 'customized'}\n"
936 assert reconcile["theirs"] == "def GET(request): return {'v': 2}\n"
937
938
939def test_reconcile_force_overwrites_conflict(tmp_path):
940 packages_root, data_dir, object_root = _install_reconcile_fixture(tmp_path, edit_object=True)
941 _bump_reconcile_package(
942 packages_root,
943 version="0.2.0",
944 object_code="def GET(request): return {'v': 2}\n",
945 )
946
947 result = object_packages.install_package(
948 "hello-world",
949 root=packages_root,
950 base_dir=data_dir,
951 object_roots=[object_root],
952 allow_replace=True,
953 force=True,
954 )
955
956 assert result["objects"][0]["status"] == "forced"
957 assert result["reconciles"] == []
958 assert (object_root / "hello" / "world.py").read_text() == "def GET(request): return {'v': 2}\n"
959
960 baseline = object_package_baselines.load_baseline("hello-world", base_dir=data_dir)
961 assert baseline["objects"]["hello_world"] == object_package_baselines.sha256_text(
962 "def GET(request): return {'v': 2}\n"
963 )
964
965
966def test_reconcile_resolve_take_theirs_writes_live_and_baseline(tmp_path):
967 packages_root, data_dir, object_root = _install_reconcile_fixture(tmp_path, edit_object=True)
968 _bump_reconcile_package(
969 packages_root,
970 version="0.2.0",
971 object_code="def GET(request): return {'v': 2}\n",
972 )
973 result = object_packages.install_package(
974 "hello-world",
975 root=packages_root,
976 base_dir=data_dir,
977 object_roots=[object_root],
978 allow_replace=True,
979 )
980 reconcile_id = result["objects"][0]["reconcile_id"]
981
982 resolved = object_reconciles.resolve_reconcile(
983 reconcile_id,
984 "take_theirs",
985 base_dir=data_dir,
986 object_roots=[object_root],
987 resolved_at="2026-07-08T00:00:00Z",
988 )
989
990 assert resolved["status"] == "resolved"
991 assert resolved["resolution"] == {"choice": "take_theirs", "resolved_at": "2026-07-08T00:00:00Z"}
992 assert (object_root / "hello" / "world.py").read_text() == "def GET(request): return {'v': 2}\n"
993
994 status = object_packages.package_status(
995 "hello-world", root=packages_root, base_dir=data_dir, object_roots=[object_root]
996 )
997 assert status["pending_reconciles"] == 0
998 object_artifact = next(a for a in status["artifacts"] if a["kind"] == "object")
999 assert object_artifact["state"] == "pristine"
1000
1001
1002def test_reconcile_resolve_keep_mine_preserves_live_and_updates_baseline(tmp_path):
1003 packages_root, data_dir, object_root = _install_reconcile_fixture(tmp_path, edit_object=True)
1004 _bump_reconcile_package(
1005 packages_root,
1006 version="0.2.0",
1007 object_code="def GET(request): return {'v': 2}\n",
1008 )
1009 result = object_packages.install_package(
1010 "hello-world",
1011 root=packages_root,
1012 base_dir=data_dir,
1013 object_roots=[object_root],
1014 allow_replace=True,
1015 )
1016 reconcile_id = result["objects"][0]["reconcile_id"]
1017
1018 resolved = object_reconciles.resolve_reconcile(
1019 reconcile_id,
1020 "keep_mine",
1021 base_dir=data_dir,
1022 object_roots=[object_root],
1023 resolved_at="2026-07-08T00:00:00Z",
1024 )
1025
1026 assert resolved["status"] == "resolved"
1027 assert resolved["resolution"]["choice"] == "keep_mine"
1028 # Live content is untouched — the operator's customization survives.
1029 assert (
1030 object_root / "hello" / "world.py"
1031 ).read_text() == "def GET(request): return {'v': 'customized'}\n"
1032
1033 status = object_packages.package_status(
1034 "hello-world", root=packages_root, base_dir=data_dir, object_roots=[object_root]
1035 )
1036 assert status["pending_reconciles"] == 0
1037 # Baseline now reads sha_theirs, so live (still "mine") reads customized
1038 # against the new upstream baseline — the operator's choice is durable.
1039 object_artifact = next(a for a in status["artifacts"] if a["kind"] == "object")
1040 assert object_artifact["state"] == "customized"
1041
1042
1043def test_reconcile_schema_conflict_and_resolve(tmp_path):
1044 # Base ships id:text. The operator changes id's type to "number" *and*
1045 # the upgrade changes id's type to "boolean": the same field diverged on
1046 # both sides, so field-union merge cannot resolve it and it must still
1047 # park as a conflict (the "email" addition alone would have merged).
1048 packages_root, data_dir, object_root = _install_reconcile_fixture(tmp_path, edit_schema=True)
1049 _bump_reconcile_package(
1050 packages_root,
1051 version="0.2.0",
1052 schema_fields=[
1053 {"name": "id", "type": "boolean"},
1054 {"name": "email", "type": "text"},
1055 ],
1056 )
1057
1058 result = object_packages.install_package(
1059 "hello-world",
1060 root=packages_root,
1061 base_dir=data_dir,
1062 object_roots=[object_root],
1063 allow_replace=True,
1064 )
1065
1066 assert result["schemas"][0]["status"] == "conflict"
1067 assert result["schemas"][0]["collisions"] == ["id"]
1068 reconcile_id = result["schemas"][0]["reconcile_id"]
1069 assert result["reconciles"] == [reconcile_id]
1070
1071 live_before = object_schemas.get_schema("contacts", base_dir=data_dir, roots=[object_root])
1072 assert live_before["field_count"] == 2
1073 assert {f["name"] for f in live_before["fields"]} == {"id", "x_priority"}
1074
1075 reconcile_record = object_reconciles.get_reconcile(reconcile_id, base_dir=data_dir)
1076 assert reconcile_record["collisions"] == ["id"]
1077
1078 resolved = object_reconciles.resolve_reconcile(
1079 reconcile_id,
1080 "take_theirs",
1081 base_dir=data_dir,
1082 object_roots=[object_root],
1083 resolved_at="2026-07-08T00:00:00Z",
1084 )
1085 assert resolved["status"] == "resolved"
1086
1087 live_after = object_schemas.get_schema("contacts", base_dir=data_dir, roots=[object_root])
1088 assert {f["name"] for f in live_after["fields"]} == {"id", "email"}
1089
1090 baseline_after = object_package_baselines.load_baseline("hello-world", base_dir=data_dir)
1091 assert {f["name"] for f in baseline_after["schema_bodies"]["contacts"]["fields"]} == {"id", "email"}
1092
1093 status = object_packages.package_status(
1094 "hello-world", root=packages_root, base_dir=data_dir, object_roots=[object_root]
1095 )
1096 schema_artifact = next(a for a in status["artifacts"] if a["kind"] == "schema")
1097 assert schema_artifact["state"] == "pristine"
1098 assert status["pending_reconciles"] == 0
1099
1100
1101def test_reconcile_schema_merges_additive_changes_without_conflict(tmp_path):
1102 # Phase 4a / Rule 3: schemas are additive, so an operator-added field and
1103 # a package-added field on the same base should both survive an upgrade
1104 # via field-union merge, with no reconcile parked.
1105 packages_root = tmp_path / "packages"
1106 data_dir = tmp_path / "data"
1107 object_root = tmp_path / "objects"
1108 object_root.mkdir()
1109
1110 write_package(
1111 packages_root,
1112 "hello-world",
1113 _reconcile_manifest("0.1.0"),
1114 files=(
1115 ("objects/hello/world.py", "def GET(request): return {'v': 1}\n"),
1116 (
1117 "schemas/contacts.json",
1118 json.dumps(
1119 {
1120 "name": "contacts",
1121 "fields": [
1122 {"name": "id", "type": "text"},
1123 {"name": "name", "type": "text"},
1124 ],
1125 }
1126 ),
1127 ),
1128 ),
1129 )
1130 object_packages.install_package(
1131 "hello-world", root=packages_root, base_dir=data_dir, object_roots=[object_root]
1132 )
1133
1134 # Operator adds a local field directly to the live schema.
1135 object_schemas.replace_schema(
1136 "contacts",
1137 {
1138 "name": "contacts",
1139 "fields": [
1140 {"name": "id", "type": "text"},
1141 {"name": "name", "type": "text"},
1142 {"name": "x_priority", "type": "text"},
1143 ],
1144 },
1145 base_dir=data_dir,
1146 )
1147
1148 # Upgrade ships its own new field, on the same base.
1149 _bump_reconcile_package(
1150 packages_root,
1151 version="0.2.0",
1152 schema_fields=[
1153 {"name": "id", "type": "text"},
1154 {"name": "name", "type": "text"},
1155 {"name": "status", "type": "text"},
1156 ],
1157 )
1158
1159 result = object_packages.install_package(
1160 "hello-world",
1161 root=packages_root,
1162 base_dir=data_dir,
1163 object_roots=[object_root],
1164 allow_replace=True,
1165 )
1166
1167 assert result["schemas"][0]["status"] == "merged"
1168 assert "reconcile_id" not in result["schemas"][0]
1169 assert result["reconciles"] == []
1170
1171 live = object_schemas.get_schema("contacts", base_dir=data_dir, roots=[object_root])
1172 assert {f["name"] for f in live["fields"]} == {"id", "name", "x_priority", "status"}
1173
1174 baseline = object_package_baselines.load_baseline("hello-world", base_dir=data_dir)
1175 assert {f["name"] for f in baseline["schema_bodies"]["contacts"]["fields"]} == {"id", "name", "status"}
1176
1177
1178def test_reconcile_schema_without_baseline_body_falls_back_to_conflict(tmp_path):
1179 # Backward-compat: a baseline recorded before this feature existed has no
1180 # "schema_bodies" entry. A both-changed schema must still fall back to
1181 # the old park-a-conflict behavior instead of crashing.
1182 packages_root, data_dir, object_root = _install_reconcile_fixture(tmp_path, edit_schema=True)
1183
1184 baseline_file = object_package_baselines.baseline_path("hello-world", base_dir=data_dir)
1185 baseline = json.loads(baseline_file.read_text())
1186 del baseline["schema_bodies"]
1187 baseline_file.write_text(json.dumps(baseline))
1188
1189 _bump_reconcile_package(
1190 packages_root,
1191 version="0.2.0",
1192 schema_fields=[
1193 {"name": "id", "type": "text"},
1194 {"name": "email", "type": "text"},
1195 ],
1196 )
1197
1198 result = object_packages.install_package(
1199 "hello-world",
1200 root=packages_root,
1201 base_dir=data_dir,
1202 object_roots=[object_root],
1203 allow_replace=True,
1204 )
1205
1206 assert result["schemas"][0]["status"] == "conflict"
1207 assert "reconcile_id" in result["schemas"][0]
1208 live = object_schemas.get_schema("contacts", base_dir=data_dir, roots=[object_root])
1209 assert {f["name"] for f in live["fields"]} == {"id", "x_priority"}
1210
1211
1212def test_reconcile_schema_resolve_keep_mine_updates_baseline_schema_body(tmp_path):
1213 packages_root, data_dir, object_root = _install_reconcile_fixture(tmp_path, edit_schema=True)
1214 _bump_reconcile_package(
1215 packages_root,
1216 version="0.2.0",
1217 schema_fields=[
1218 {"name": "id", "type": "boolean"},
1219 {"name": "email", "type": "text"},
1220 ],
1221 )
1222
1223 result = object_packages.install_package(
1224 "hello-world",
1225 root=packages_root,
1226 base_dir=data_dir,
1227 object_roots=[object_root],
1228 allow_replace=True,
1229 )
1230 reconcile_id = result["schemas"][0]["reconcile_id"]
1231
1232 resolved = object_reconciles.resolve_reconcile(
1233 reconcile_id,
1234 "keep_mine",
1235 base_dir=data_dir,
1236 object_roots=[object_root],
1237 )
1238 assert resolved["status"] == "resolved"
1239
1240 # Live keeps the operator's version...
1241 live = object_schemas.get_schema("contacts", base_dir=data_dir, roots=[object_root])
1242 assert {f["name"] for f in live["fields"]} == {"id", "x_priority"}
1243
1244 # ...but the baseline body advances to the new upstream shape, so a
1245 # future upgrade diffs against what was actually shipped.
1246 baseline = object_package_baselines.load_baseline("hello-world", base_dir=data_dir)
1247 assert {f["name"] for f in baseline["schema_bodies"]["contacts"]["fields"]} == {"id", "email"}
1248
1249
1250def test_reconcile_package_status_counts_pending_reconciles(tmp_path):
1251 packages_root, data_dir, object_root = _install_reconcile_fixture(tmp_path, edit_object=True)
1252 _bump_reconcile_package(
1253 packages_root,
1254 version="0.2.0",
1255 object_code="def GET(request): return {'v': 2}\n",
1256 )
1257
1258 object_packages.install_package(
1259 "hello-world",
1260 root=packages_root,
1261 base_dir=data_dir,
1262 object_roots=[object_root],
1263 allow_replace=True,
1264 )
1265
1266 status = object_packages.package_status(
1267 "hello-world", root=packages_root, base_dir=data_dir, object_roots=[object_root]
1268 )
1269 assert status["pending_reconciles"] == 1
1270
1271
1272# --- Phase 3: override objects (conflict-free customization, Rule 2) --------
1273#
1274# See docs/upgrade-and-customization.md (Rule 2). An override shadows a
1275# package object by id without touching the package copy, so install/
1276# reconcile logic (which always targets get_base_object_roots()) never sees
1277# a conflict for an overridden object, and the package copy stays
1278# upgradeable.
1279
1280
1281def test_package_status_reports_overridden_flag(tmp_path, monkeypatch):
1282 packages_root = tmp_path / "packages"
1283 data_dir = tmp_path / "data"
1284 object_root = tmp_path / "objects"
1285 object_root.mkdir()
1286 override_root = tmp_path / "overrides"
1287 monkeypatch.delenv("DBBASIC_OVERRIDES_DIR", raising=False)
1288 write_package(
1289 packages_root,
1290 "hello-world",
1291 _reconcile_manifest("0.1.0"),
1292 files=(
1293 ("objects/hello/world.py", "def GET(request): return {'v': 1}\n"),
1294 (
1295 "schemas/contacts.json",
1296 json.dumps({"name": "contacts", "fields": [{"name": "id", "type": "text"}]}),
1297 ),
1298 ),
1299 )
1300 object_packages.install_package(
1301 "hello-world", root=packages_root, base_dir=data_dir, object_roots=[object_root]
1302 )
1303
1304 status_before = object_packages.package_status(
1305 "hello-world", root=packages_root, base_dir=data_dir, object_roots=[object_root]
1306 )
1307 object_artifact = next(a for a in status_before["artifacts"] if a["kind"] == "object")
1308 assert object_artifact["overridden"] is False
1309
1310 monkeypatch.setenv("DBBASIC_OVERRIDES_DIR", str(override_root))
1311 override_file = override_root / "hello" / "world.py"
1312 override_file.parent.mkdir(parents=True)
1313 override_file.write_text("def GET(request): return {'v': 'overridden'}\n")
1314
1315 status_after = object_packages.package_status(
1316 "hello-world", root=packages_root, base_dir=data_dir, object_roots=[object_root]
1317 )
1318 object_artifact_after = next(a for a in status_after["artifacts"] if a["kind"] == "object")
1319 assert object_artifact_after["overridden"] is True
1320 # pristine/customized state is computed from the base-root copy only —
1321 # the override never influences it.
1322 assert object_artifact_after["state"] == "pristine"
1323
1324
1325def test_upgrade_fast_forwards_base_copy_without_conflict_when_overridden(tmp_path, monkeypatch):
1326 packages_root = tmp_path / "packages"
1327 data_dir = tmp_path / "data"
1328 object_root = tmp_path / "objects"
1329 override_root = tmp_path / "overrides"
1330 monkeypatch.setenv("DBBASIC_OBJECTS_DIR", str(object_root))
1331 monkeypatch.delenv("DBBASIC_OVERRIDES_DIR", raising=False)
1332
1333 write_package(
1334 packages_root,
1335 "hello-world",
1336 _reconcile_manifest("0.1.0"),
1337 files=(
1338 ("objects/hello/world.py", "def GET(request): return {'v': 1}\n"),
1339 (
1340 "schemas/contacts.json",
1341 json.dumps({"name": "contacts", "fields": [{"name": "id", "type": "text"}]}),
1342 ),
1343 ),
1344 )
1345
1346 object_packages.install_package(
1347 "hello-world",
1348 root=packages_root,
1349 base_dir=data_dir,
1350 object_roots=object_namespace.get_base_object_roots(),
1351 )
1352
1353 # Enable overrides and customize hello_world via an override. The
1354 # package copy under object_root is never touched by this.
1355 monkeypatch.setenv("DBBASIC_OVERRIDES_DIR", str(override_root))
1356 override_file = object_namespace.override_path("hello_world")
1357 override_file.parent.mkdir(parents=True)
1358 override_file.write_text("def GET(request): return {'v': 'overridden'}\n")
1359 assert object_namespace.resolve_object_id("hello_world") == override_file
1360
1361 # Ship an upgrade with different shipped object content.
1362 _bump_reconcile_package(
1363 packages_root,
1364 version="0.2.0",
1365 object_code="def GET(request): return {'v': 2}\n",
1366 )
1367
1368 result = object_packages.install_package(
1369 "hello-world",
1370 root=packages_root,
1371 base_dir=data_dir,
1372 object_roots=object_namespace.get_base_object_roots(),
1373 allow_replace=True,
1374 )
1375
1376 # The base/package copy fast-forwards cleanly: no conflict, because the
1377 # base copy (not the override) was pristine going into the upgrade.
1378 assert result["objects"][0]["status"] == "updated"
1379 assert result["reconciles"] == []
1380 assert (object_root / "hello" / "world.py").read_text() == "def GET(request): return {'v': 2}\n"
1381
1382 # The override is completely untouched by the upgrade.
1383 assert override_file.read_text() == "def GET(request): return {'v': 'overridden'}\n"
1384
1385 status = object_packages.package_status(
1386 "hello-world",
1387 root=packages_root,
1388 base_dir=data_dir,
1389 object_roots=object_namespace.get_base_object_roots(),
1390 )
1391 object_artifact = next(a for a in status["artifacts"] if a["kind"] == "object")
1392 assert object_artifact["state"] == "pristine"
1393 assert object_artifact["overridden"] is True
1394
1395
1396# --- where an install actually writes -----------------------------------------
1397#
1398# The bug this guards was not a crash. install_package defaulted base_dir to
1399# the literal "data" and ignored DBBASIC_DATA_DIR, so an install run with the
1400# environment set to somewhere else reported "status": "written" for every
1401# schema and seed -- into a freshly created ./data beside the checkout that
1402# nothing reads. Nothing failed, nothing warned, and the package was simply
1403# absent from the running server. Hit twice in one afternoon on a box whose
1404# layout was well understood, which is why the default changed rather than
1405# somebody remembering harder.
1406
1407def test_an_install_writes_where_the_environment_says(tmp_path, monkeypatch):
1408 packages_root = tmp_path / "packages"
1409 object_root = tmp_path / "objects"
1410 live = tmp_path / "live-data"
1411 decoy = tmp_path / "cwd"
1412 decoy.mkdir()
1413
1414 write_package(
1415 packages_root,
1416 "hello-world",
1417 {
1418 "id": "hello-world",
1419 "name": "Hello World",
1420 "version": "0.1.0",
1421 "objects": [{"id": "hello_world", "path": "objects/hello/world.py"}],
1422 "schemas": [{"collection": "widgets", "path": "schemas/widgets.json"}],
1423 },
1424 files=(
1425 ("objects/hello/world.py", "def GET(request): return {'ok': True}\n"),
1426 ("schemas/widgets.json",
1427 '{"name": "widgets", "fields": [{"name": "id"}, {"name": "title"}]}\n'),
1428 ),
1429 )
1430
1431 monkeypatch.chdir(decoy)
1432 monkeypatch.setenv("DBBASIC_DATA_DIR", str(live))
1433
1434 result = object_packages.install_package(
1435 "hello-world", root=packages_root, object_roots=[object_root])
1436
1437 assert (live / "schemas" / "widgets.json").is_file()
1438 # And nothing was created in the working directory, which is where the
1439 # old default would have put it.
1440 assert not (decoy / "data").exists()
1441
1442 # The result says WHERE, so "written" is a claim a caller can check.
1443 assert result["data_dir"] == str(live.resolve())
1444
1445
1446def test_an_explicit_base_dir_still_wins_over_the_environment(tmp_path, monkeypatch):
1447 """Every real caller passes one -- the server always does -- and the
1448 environment must not quietly override somebody who was specific."""
1449 packages_root = tmp_path / "packages"
1450 object_root = tmp_path / "objects"
1451 chosen = tmp_path / "chosen"
1452
1453 write_package(
1454 packages_root,
1455 "hello-world",
1456 {
1457 "id": "hello-world",
1458 "name": "Hello World",
1459 "version": "0.1.0",
1460 "objects": [{"id": "hello_world", "path": "objects/hello/world.py"}],
1461 "schemas": [{"collection": "widgets", "path": "schemas/widgets.json"}],
1462 },
1463 files=(
1464 ("objects/hello/world.py", "def GET(request): return {'ok': True}\n"),
1465 ("schemas/widgets.json",
1466 '{"name": "widgets", "fields": [{"name": "id"}, {"name": "title"}]}\n'),
1467 ),
1468 )
1469
1470 monkeypatch.setenv("DBBASIC_DATA_DIR", str(tmp_path / "ignored"))
1471 result = object_packages.install_package(
1472 "hello-world", root=packages_root, base_dir=chosen,
1473 object_roots=[object_root])
1474
1475 assert (chosen / "schemas" / "widgets.json").is_file()
1476 assert not (tmp_path / "ignored").exists()
1477 assert result["data_dir"] == str(chosen.resolve())
1478
1479
1480def test_resolve_base_dir_prefers_explicit_then_environment_then_data(monkeypatch):
1481 monkeypatch.delenv("DBBASIC_DATA_DIR", raising=False)
1482 assert object_packages.resolve_base_dir() == Path("data")
1483 assert object_packages.resolve_base_dir("/tmp/x") == Path("/tmp/x")
1484
1485 monkeypatch.setenv("DBBASIC_DATA_DIR", "/srv/live")
1486 assert object_packages.resolve_base_dir() == Path("/srv/live")
1487 assert object_packages.resolve_base_dir("/tmp/x") == Path("/tmp/x")
1488
1489
1490def test_a_dry_run_reports_the_same_data_dir_it_would_install_into(tmp_path,
1491 monkeypatch):
1492 """A plan that does not say where it would write is a plan nobody can
1493 check before running it."""
1494 packages_root = tmp_path / "packages"
1495 object_root = tmp_path / "objects"
1496 live = tmp_path / "live-data"
1497
1498 write_package(
1499 packages_root,
1500 "hello-world",
1501 {
1502 "id": "hello-world",
1503 "name": "Hello World",
1504 "version": "0.1.0",
1505 "objects": [{"id": "hello_world", "path": "objects/hello/world.py"}],
1506 },
1507 files=(("objects/hello/world.py", "def GET(request): return {'ok': True}\n"),),
1508 )
1509
1510 monkeypatch.setenv("DBBASIC_DATA_DIR", str(live))
1511 plan = object_packages.dry_run_package(
1512 "hello-world", root=packages_root, object_roots=[object_root])
1513 assert plan["data_dir"] == str(live.resolve())
1514
1515
1516def test_a_new_package_object_installs_into_the_base_root_not_overrides(tmp_path):
1517 """A package install that lands in the override root is a silent no-run.
1518
1519 get_object_roots() returns [override, base] in LOOKUP order, so the
1520 override root is roots[0] -- and installing new objects there
1521 contradicted object_namespace.get_base_object_roots's own stated
1522 contract ("the root packages install into and reconcile against ...
1523 the pristine, upgradeable copy").
1524
1525 The consequence was not cosmetic, which is why this test exists at
1526 the level of `kind` rather than just the path: iter_object_sources
1527 labels anything under the override root kind="override", and
1528 object_handlers.build_index indexes ONLY kind=="system" (Decision 2,
1529 user-authored handlers deferred). So a package object declaring
1530 HANDLES installed cleanly, reported "written", and then never
1531 received a single event. Caught in production on system_wallet_books,
1532 not by a test.
1533 """
1534 packages_root = tmp_path / "packages"
1535 base_root = tmp_path / "objects"
1536 override_root = tmp_path / "overrides"
1537 base_root.mkdir()
1538 override_root.mkdir()
1539
1540 handler_source = 'HANDLES = ["widgets.record.created"]\n\n\ndef EVENT(request):\n return {"ok": True}\n'
1541 write_package(
1542 packages_root, "handler-pkg",
1543 {"id": "handler-pkg", "name": "Handler", "version": "0.1.0",
1544 "objects": [{"id": "system_widget_books", "path": "objects/system/widget_books.py"}]},
1545 files=[("objects/system/widget_books.py", handler_source)],
1546 )
1547
1548 # Roots in real lookup order: override first, base last.
1549 roots = [override_root, base_root]
1550 result = object_packages.install_package(
1551 "handler-pkg", root=packages_root, base_dir=tmp_path / "data",
1552 object_roots=roots)
1553 assert result["objects"][0]["status"] == "written"
1554
1555 assert (base_root / "system" / "widget_books.py").is_file()
1556 assert not (override_root / "system" / "widget_books.py").exists()
1557
1558 sources = {s.object_id: s for s in object_namespace.iter_object_sources(roots)}
1559 assert sources["system_widget_books"].kind == "system"
1560
1561 import object_handlers
1562 index = object_handlers.build_index(roots)
1563 assert index.get("widgets.record.created") == ["system_widget_books"]
1564
1565
1566def test_an_overridden_object_stays_in_the_override_root_on_upgrade(tmp_path):
1567 """The other half: a customized object must not be yanked out of the
1568 override root by an upgrade -- that is what overrides are FOR."""
1569 packages_root = tmp_path / "packages"
1570 base_root = tmp_path / "objects"
1571 override_root = tmp_path / "overrides"
1572 base_root.mkdir()
1573 override_root.mkdir()
1574 roots = [override_root, base_root]
1575
1576 write_package(
1577 packages_root, "widget-pkg",
1578 {"id": "widget-pkg", "name": "Widget", "version": "0.1.0",
1579 "objects": [{"id": "system_widget", "path": "objects/system/widget.py"}]},
1580 files=[("objects/system/widget.py", "def GET(request):\n return {}\n")],
1581 )
1582 object_packages.install_package("widget-pkg", root=packages_root,
1583 base_dir=tmp_path / "data", object_roots=roots)
1584
1585 # An operator customizes it: the object now also lives in overrides.
1586 customized = override_root / "system" / "widget.py"
1587 customized.parent.mkdir(parents=True, exist_ok=True)
1588 customized.write_text("def GET(request):\n return {'mine': True}\n")
1589
1590 update_package(
1591 packages_root, "widget-pkg",
1592 {"id": "widget-pkg", "name": "Widget", "version": "0.2.0",
1593 "objects": [{"id": "system_widget", "path": "objects/system/widget.py"}]},
1594 files=[("objects/system/widget.py", "def GET(request):\n return {'v2': True}\n")],
1595 )
1596 object_packages.install_package("widget-pkg", root=packages_root,
1597 base_dir=tmp_path / "data", object_roots=roots,
1598 allow_replace=True)
1599 assert customized.is_file()