ai-context-framework 0.0.3.58__py3-none-any.whl

acf.py

@@ -0,0 +1,36 @@
+#!/usr/bin/env python3
+"""Compatibility shim for the ACF CLI.
+
+The package runtime lives under :mod:`ai_context_framework`. This top-level
+module remains importable for legacy scripts and for ``python acf.py``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any
+
+from ai_context_framework import runtime as _runtime
+from ai_context_framework.version import VERSION
+
+
+ROOT = _runtime.ROOT
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    _runtime.ROOT = ROOT
+    _runtime._sync_runtime_part_globals()
+    return _runtime.main(argv)
+
+
+def __getattr__(name: str) -> Any:
+    _runtime.ROOT = ROOT
+    _runtime._sync_runtime_part_globals()
+    try:
+        return getattr(_runtime, name)
+    except AttributeError as exc:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}") from exc
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ai_context_framework/__init__.py

@@ -0,0 +1,7 @@
+"""AI Context Framework package.
+
+The package CLI entrypoint is :mod:`ai_context_framework.cli`; top-level
+``acf.py`` remains as a compatibility shim.
+"""
+
+__all__: tuple[str, ...] = ()

ai_context_framework/cli.py

@@ -0,0 +1,11 @@
+"""Package CLI entrypoint."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from ai_context_framework import runtime
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    return runtime.main(argv)

ai_context_framework/commands/__init__.py

@@ -0,0 +1,2 @@
+"""Command handlers for ACF."""
+

ai_context_framework/commands/archive.py

@@ -0,0 +1,138 @@
+"""Command handlers for archive workflows."""
+
+from __future__ import annotations
+
+import argparse
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Callable
+
+from ai_context_framework.json_contract import dry_run_enabled, emit_write_result, json_enabled, print_json, set_result_payload
+from ai_context_framework.markers import (
+    ARCHIVE_INDEX_MARKER_END,
+    ARCHIVE_INDEX_MARKER_START,
+    insert_generated_marker_block_after_heading,
+    replace_generated_marker_block,
+)
+from ai_context_framework.models import CheckResult
+from ai_context_framework.paths import require_context_root
+from ai_context_framework.tables import split_table_line
+
+
+MaybeCheckAfter = Callable[[argparse.Namespace, Path, str | None], CheckResult | None]
+
+
+@dataclass(frozen=True)
+class ArchiveDependencies:
+    maybe_check_after: MaybeCheckAfter
+    archive_index_path: Callable[..., Any]
+    read_text: Callable[..., Any]
+    render_archive_index: Callable[..., Any]
+    collect_archive_sync_rows: Callable[..., Any]
+    skipped_missing_generated_archive_details: Callable[..., Any]
+    render_archive_index_table: Callable[..., Any]
+    archive_file: Callable[..., Any]
+    current_task_path: Callable[..., Any]
+    task_plan_path: Callable[..., Any]
+    find_archive_table: Callable[..., Any]
+    archive_table_header: str
+
+
+def archive_sync_command(args: argparse.Namespace, *, deps: ArchiveDependencies) -> int:
+    root = require_context_root(args.path)
+    index_path = deps.archive_index_path(root)
+    original = deps.read_text(index_path) if index_path.exists() else deps.render_archive_index()
+    rows, skipped, warnings = deps.collect_archive_sync_rows(root)
+    skipped.extend(deps.skipped_missing_generated_archive_details(root, original))
+    generated_table = deps.render_archive_index_table(rows)
+
+    if ARCHIVE_INDEX_MARKER_START in original or ARCHIVE_INDEX_MARKER_END in original:
+        updated, changed = replace_generated_marker_block(
+            original,
+            ARCHIVE_INDEX_MARKER_START,
+            ARCHIVE_INDEX_MARKER_END,
+            generated_table,
+        )
+        initialized_marker = False
+    elif args.init_marker:
+        updated, changed = insert_generated_marker_block_after_heading(
+            original,
+            "## 归档条目",
+            ARCHIVE_INDEX_MARKER_START,
+            ARCHIVE_INDEX_MARKER_END,
+            generated_table,
+            replace_empty_table_header=deps.archive_table_header,
+        )
+        initialized_marker = True
+    else:
+        raise SystemExit("generated_marker_missing: archive/Archive_Index.md is missing ACF:ARCHIVE:INDEX-GENERATED markers")
+
+    changed_files = [index_path] if changed or not index_path.exists() else []
+    if changed_files and not dry_run_enabled(args):
+        index_path.parent.mkdir(parents=True, exist_ok=True)
+        index_path.write_text(updated, encoding="utf-8")
+    check_result = deps.maybe_check_after(args, root, None)
+    action = "would sync" if dry_run_enabled(args) else "synced"
+    extra_payload: dict[str, object] = {
+        "generated_count": len(rows),
+        "skipped_items": skipped,
+        "initialized_marker": initialized_marker,
+    }
+    if dry_run_enabled(args):
+        extra_payload["planned_block"] = generated_table
+    return emit_write_result(
+        args,
+        "archive sync",
+        f"{action} Archive index generated block",
+        changed_files,
+        check_result,
+        extra_payload=extra_payload,
+        warnings=warnings,
+    )
+
+
+def archive_current_task_command(args: argparse.Namespace, *, deps: ArchiveDependencies) -> int:
+    root = require_context_root(args.path)
+    dry_run = dry_run_enabled(args)
+    changed = deps.archive_file(root, deps.current_task_path(root), "Task", args.reason, args.force, dry_run)
+    check_result = deps.maybe_check_after(args, root, None)
+    action = "would archive" if dry_run else "archived"
+    return emit_write_result(args, "archive current-task", f"{action} current task", changed, check_result)
+
+
+def archive_task_plan_command(args: argparse.Namespace, *, deps: ArchiveDependencies) -> int:
+    root = require_context_root(args.path)
+    dry_run = dry_run_enabled(args)
+    changed = deps.archive_file(root, deps.task_plan_path(root), "Plan", args.reason, args.force, dry_run)
+    check_result = deps.maybe_check_after(args, root, None)
+    action = "would archive" if dry_run else "archived"
+    return emit_write_result(args, "archive task-plan", f"{action} task plan", changed, check_result)
+
+
+def archive_list_command(args: argparse.Namespace, *, deps: ArchiveDependencies) -> int:
+    root = require_context_root(args.path)
+    index_path = deps.archive_index_path(root)
+    rows: list[dict[str, str]] = []
+    if index_path.exists():
+        lines = deps.read_text(index_path).splitlines()
+        table, legacy = deps.find_archive_table(lines)
+        keys = ["日期", "类型", "标题", "原因", "详情"] if legacy else ["日期", "类型", "ID", "原路径", "归档路径", "状态", "原因"]
+        for line in lines[table.body_start : table.body_end]:
+            cells = split_table_line(line)
+            if len(cells) >= len(keys) and cells[0] != "暂无":
+                rows.append(dict(zip(keys, cells)))
+    payload: dict[str, object] = {
+        "command": "archive list",
+        "ok": True,
+        "context": str(root),
+        "archives": rows,
+        "error_code": None,
+        "next_actions": [],
+    }
+    set_result_payload(args, payload)
+    if json_enabled(args):
+        print_json(payload)
+    else:
+        for row in rows:
+            print(f"{row.get('日期')} {row.get('类型')} {row.get('ID') or row.get('标题')} {row.get('归档路径') or row.get('详情')}")
+    return 0

ai_context_framework/commands/decisions.py

@@ -0,0 +1,85 @@
+"""Command handlers for decision index maintenance."""
+
+from __future__ import annotations
+
+import argparse
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Callable
+
+from ai_context_framework.json_contract import dry_run_enabled, emit_write_result
+from ai_context_framework.markers import (
+    DECISIONS_INDEX_MARKER_END,
+    DECISIONS_INDEX_MARKER_START,
+    insert_generated_marker_block_after_heading,
+    replace_generated_marker_block,
+)
+from ai_context_framework.models import CheckResult
+from ai_context_framework.paths import require_context_root
+
+
+MaybeCheckAfter = Callable[[argparse.Namespace, Path, str | None], CheckResult | None]
+
+
+@dataclass(frozen=True)
+class DecisionsDependencies:
+    maybe_check_after: MaybeCheckAfter
+    decisions_index_path: Callable[..., Any]
+    read_text: Callable[..., Any]
+    collect_decision_sync_rows: Callable[..., Any]
+    skipped_missing_generated_decision_details: Callable[..., Any]
+    render_decisions_index_table: Callable[..., Any]
+
+
+def decisions_sync_command(args: argparse.Namespace, *, deps: DecisionsDependencies) -> int:
+    root = require_context_root(args.path)
+    index_path = deps.decisions_index_path(root)
+    if not index_path.exists():
+        raise SystemExit(f"sync_source_invalid: decisions index does not exist: {index_path}")
+    original = deps.read_text(index_path)
+    rows, skipped, warnings = deps.collect_decision_sync_rows(root)
+    skipped.extend(deps.skipped_missing_generated_decision_details(root, original))
+    generated_table = deps.render_decisions_index_table(rows)
+
+    if DECISIONS_INDEX_MARKER_START in original or DECISIONS_INDEX_MARKER_END in original:
+        updated, changed = replace_generated_marker_block(
+            original,
+            DECISIONS_INDEX_MARKER_START,
+            DECISIONS_INDEX_MARKER_END,
+            generated_table,
+        )
+        initialized_marker = False
+    elif args.init_marker:
+        updated, changed = insert_generated_marker_block_after_heading(
+            original,
+            "## 当前有效决策",
+            DECISIONS_INDEX_MARKER_START,
+            DECISIONS_INDEX_MARKER_END,
+            generated_table,
+            replace_empty_table_header="| ID | 标题 | 状态 | 摘要 | 详情 |",
+        )
+        initialized_marker = True
+    else:
+        raise SystemExit("generated_marker_missing: reference/Decisions_Index.md is missing ACF:DECISIONS:INDEX-GENERATED markers")
+
+    changed_files = [index_path] if changed else []
+    if changed_files and not dry_run_enabled(args):
+        index_path.write_text(updated, encoding="utf-8")
+    check_result = deps.maybe_check_after(args, root, None)
+    action = "would sync" if dry_run_enabled(args) else "synced"
+    extra_payload: dict[str, object] = {
+        "generated_count": len(rows),
+        "skipped_items": skipped,
+        "initialized_marker": initialized_marker,
+    }
+    if dry_run_enabled(args):
+        extra_payload["planned_block"] = generated_table
+    return emit_write_result(
+        args,
+        "decisions sync",
+        f"{action} Decisions index generated block",
+        changed_files,
+        check_result,
+        extra_payload=extra_payload,
+        warnings=warnings,
+    )

ai_context_framework/commands/doctor.py

@@ -0,0 +1,75 @@
+"""Command handler for doctor diagnostics."""
+
+from __future__ import annotations
+
+import argparse
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Callable
+
+from ai_context_framework.constants import JSON_SCHEMA_VERSION
+from ai_context_framework.json_contract import json_enabled, print_json, set_result_payload
+from ai_context_framework.paths import require_context_root
+
+
+@dataclass(frozen=True)
+class DoctorDependencies:
+    doctor_project_payload: Callable[..., Any]
+    doctor_single_context_payload: Callable[..., Any]
+    doctor_summary: Callable[..., Any]
+    doctor_projects_next_actions: Callable[..., Any]
+
+
+def doctor_command(args: argparse.Namespace, *, deps: DoctorDependencies) -> int:
+    if getattr(args, "projects", None):
+        if getattr(args, "fix", "none") != "none":
+            raise SystemExit(
+                "doctor_projects_fix_unsupported: --projects is read-only; "
+                "run single-project doctor with --fix for write repairs"
+            )
+        if getattr(args, "report", False) or getattr(args, "draft_semantic", False):
+            raise SystemExit(
+                "doctor_projects_write_unsupported: --projects is read-only; "
+                "run single-project doctor with --report or --draft-semantic"
+            )
+        project_payloads = [deps.doctor_project_payload(args, project) for project in args.projects]
+        ok = all(bool(item.get("ok")) for item in project_payloads)
+        findings = [
+            finding
+            for item in project_payloads
+            for finding in item.get("findings", [])
+            if isinstance(finding, dict)
+        ]
+        changed_files = [
+            changed_file
+            for item in project_payloads
+            for changed_file in item.get("changed_files", [])
+            if isinstance(changed_file, str)
+        ]
+        payload: dict[str, object] = {
+            "schema_version": JSON_SCHEMA_VERSION,
+            "command": "doctor",
+            "ok": ok,
+            "projects": project_payloads,
+            "summary": deps.doctor_summary(findings),
+            "changed_files": sorted(dict.fromkeys(changed_files)),
+            "error_code": None if ok else "doctor_failed",
+            "message": "" if ok else "one or more projects failed",
+            "next_actions": deps.doctor_projects_next_actions(project_payloads, findings, getattr(args, "fix", "none"), ok),
+        }
+    else:
+        payload = deps.doctor_single_context_payload(args, require_context_root(args.path))
+    set_result_payload(args, payload)
+    if json_enabled(args):
+        print_json(payload)
+    else:
+        if "projects" in payload:
+            for item in payload["projects"]:
+                if isinstance(item, dict):
+                    print(f"{item.get('context')}: {item.get('summary', {}).get('findings_total', 0)} finding(s)")
+        else:
+            print(f"doctor findings: {payload['summary']['findings_total']}")
+            for finding in payload.get("findings", []):
+                if isinstance(finding, dict):
+                    print(f"{finding.get('severity')}: {finding.get('code')} - {finding.get('message')}")
+    return 0 if payload.get("ok") else 1

ai_context_framework/commands/edit_link.py

@@ -0,0 +1,298 @@
+"""Edit, linkify, and link command handlers."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Callable
+from pathlib import Path
+
+from ai_context_framework.json_contract import (
+    dry_run_enabled,
+    emit_write_result,
+    json_enabled,
+    print_json,
+    set_result_payload,
+)
+from ai_context_framework.markdown import (
+    append_section_text,
+    find_section,
+    linkify_markdown_text,
+    markdown_heading_anchor_for,
+    markdown_link_target_for,
+    render_markdown_link,
+    replace_section_text,
+    section_body,
+)
+from ai_context_framework.models import CheckResult
+from ai_context_framework.observability import atomic_write_text
+from ai_context_framework.paths import is_relative_to, require_context_root
+from ai_context_framework.tables import parse_cell_updates, upsert_table_row
+
+
+LINKIFY_DEFAULT_DIRS = ("active", "reference", "rules", "decisions")
+LINKIFY_DEFAULT_FILES = ("worklog/Worklog_Index.md", "archive/Archive_Index.md")
+CheckAfter = Callable[[argparse.Namespace, Path], CheckResult | None]
+
+
+def resolve_context_markdown_file(root: Path, target: Path) -> Path:
+    root = root.resolve()
+    if target.is_absolute():
+        resolved = target.resolve()
+    else:
+        root_candidate = (root / target).resolve()
+        if not is_relative_to(root_candidate, root):
+            raise SystemExit(f"target file is outside context root: {target}")
+
+        cwd_candidate = (Path.cwd() / target).resolve()
+        if cwd_candidate.exists() and is_relative_to(cwd_candidate, root):
+            resolved = cwd_candidate
+        else:
+            resolved = root_candidate
+
+    if not is_relative_to(resolved, root):
+        raise SystemExit(f"target file is outside context root: {target}")
+    if resolved.suffix.lower() != ".md":
+        raise SystemExit(f"target file must be Markdown (.md): {resolved}")
+    if not resolved.exists():
+        raise SystemExit(f"target file does not exist: {resolved}")
+    if not resolved.is_file():
+        raise SystemExit(f"target path is not a file: {resolved}")
+    return resolved
+
+
+def resolve_context_file(root: Path, target: Path, *, must_exist: bool = True) -> Path:
+    root = root.resolve()
+    if target.is_absolute():
+        resolved = target.resolve()
+    else:
+        root_candidate = (root / target).resolve()
+        if not is_relative_to(root_candidate, root):
+            raise SystemExit(f"target file is outside context root: {target}")
+
+        cwd_candidate = (Path.cwd() / target).resolve()
+        if cwd_candidate.exists() and is_relative_to(cwd_candidate, root):
+            resolved = cwd_candidate
+        else:
+            resolved = root_candidate
+
+    if not is_relative_to(resolved, root):
+        raise SystemExit(f"target file is outside context root: {target}")
+    if must_exist and not resolved.exists():
+        raise SystemExit(f"target file does not exist: {resolved}")
+    if must_exist and not resolved.is_file():
+        raise SystemExit(f"target path is not a file: {resolved}")
+    return resolved
+
+
+def read_edit_input(args: argparse.Namespace) -> str:
+    text = getattr(args, "text", None)
+    input_path = getattr(args, "input", None)
+    if text is not None and input_path is not None:
+        raise SystemExit("use either --text or --input, not both")
+    if text is not None:
+        return text
+    if input_path is not None:
+        resolved = input_path.resolve()
+        if not resolved.is_file():
+            raise SystemExit(f"edit input file does not exist: {resolved}")
+        return resolved.read_text(encoding="utf-8")
+    if not sys.stdin.isatty():
+        return sys.stdin.read()
+    raise SystemExit("edit command requires --text, --input, or stdin")
+
+
+def linkify_candidate_files(root: Path, args: argparse.Namespace) -> list[Path]:
+    files: set[Path] = set()
+    for dirname in LINKIFY_DEFAULT_DIRS:
+        directory = root / dirname
+        if directory.exists():
+            files.update(path for path in directory.rglob("*.md") if path.is_file())
+    for rel in LINKIFY_DEFAULT_FILES:
+        file_path = root / rel
+        if file_path.is_file():
+            files.add(file_path)
+    if getattr(args, "include_worklog_daily", False):
+        daily = root / "worklog" / "daily"
+        if daily.exists():
+            files.update(path for path in daily.rglob("*.md") if path.is_file())
+    if getattr(args, "include_archive", False):
+        archive = root / "archive"
+        if archive.exists():
+            files.update(path for path in archive.rglob("*.md") if path.is_file())
+    return sorted(files)
+
+
+def linkify_command(args: argparse.Namespace, *, maybe_check_after: CheckAfter) -> int:
+    if getattr(args, "format", "markdown") != "markdown":
+        raise SystemExit("linkify currently supports only --format markdown")
+    root = require_context_root(args.path)
+    dry_run = dry_run_enabled(args)
+    changed_files: list[Path] = []
+    updated_entries: list[dict[str, object]] = []
+    skipped_entries: list[dict[str, str]] = []
+    for md_file in linkify_candidate_files(root, args):
+        original = md_file.read_text(encoding="utf-8")
+        updated, replacements, skipped = linkify_markdown_text(
+            root,
+            md_file,
+            original,
+            allow_missing=bool(getattr(args, "allow_missing", False)),
+        )
+        rel_file = md_file.relative_to(root).as_posix()
+        skipped_entries.extend({"file": rel_file, **entry} for entry in skipped)
+        if updated == original:
+            continue
+        changed_files.append(md_file)
+        updated_entries.append({"path": rel_file, "replacements": replacements})
+        if not dry_run:
+            atomic_write_text(md_file, updated)
+
+    check_result = maybe_check_after(args, root)
+    action = "would linkify" if dry_run else "linkified"
+    return emit_write_result(
+        args,
+        "linkify",
+        f"{action} {len(changed_files)} file(s)",
+        changed_files,
+        check_result,
+        extra_payload={
+            "format": args.format,
+            "updated": updated_entries,
+            "skipped": skipped_entries,
+        },
+    )
+
+
+def link_add_command(args: argparse.Namespace, *, maybe_check_after: CheckAfter) -> int:
+    root = require_context_root(args.path)
+    dry_run = dry_run_enabled(args)
+    target_file = resolve_context_markdown_file(root, args.file)
+    link_target_file = resolve_context_file(root, args.target)
+    target_fragment = ""
+    if args.target_heading:
+        if link_target_file.suffix.lower() != ".md":
+            raise SystemExit("--target-heading requires a Markdown target file")
+        anchor = markdown_heading_anchor_for(link_target_file.read_text(encoding="utf-8"), args.target_heading)
+        if anchor is None:
+            raise SystemExit(f"target heading was not found: {args.target_heading}")
+        target_fragment = anchor
+    link_href = markdown_link_target_for(target_file, link_target_file, target_fragment)
+    context_target_display = link_target_file.relative_to(root).as_posix()
+    default_text = f"{context_target_display}#{target_fragment}" if target_fragment else context_target_display
+    link_text = args.text or default_text
+    bullet = f"- {render_markdown_link(link_text, link_href)}"
+
+    original = target_file.read_text(encoding="utf-8")
+    original_lines = original.splitlines()
+    body = section_body(original_lines, find_section(original_lines, args.heading))
+    duplicate_markers = {f"]({link_href})", f"](<{link_href}>)"}
+    if not args.force and any(marker in body for marker in duplicate_markers):
+        raise SystemExit(f"link already exists in section: {link_href}")
+    updated = append_section_text(original, args.heading, bullet)
+    changed_files = [target_file] if updated != original else []
+    if changed_files and not dry_run:
+        atomic_write_text(target_file, updated)
+
+    check_result = maybe_check_after(args, root)
+    action = "would add" if dry_run else "added"
+    return emit_write_result(
+        args,
+        "link add",
+        f"{action} link to {target_file}",
+        changed_files,
+        check_result,
+        extra_payload={
+            "file": target_file.relative_to(root).as_posix(),
+            "heading": args.heading,
+            "link": bullet,
+            "target": context_target_display,
+            "target_heading": args.target_heading,
+        },
+    )
+
+
+def edit_section_get_command(args: argparse.Namespace) -> int:
+    root = require_context_root(args.context)
+    target = resolve_context_markdown_file(root, args.file)
+    lines = target.read_text(encoding="utf-8").splitlines()
+    section = find_section(lines, args.heading)
+    body = section_body(lines, section)
+    payload: dict[str, object] = {
+        "command": "edit section get",
+        "ok": True,
+        "context": str(root),
+        "file": str(target),
+        "heading": args.heading,
+        "body": body,
+        "heading_line": section.heading_index + 1,
+        "body_start_line": section.body_start + 1,
+        "body_end_line": section.body_end,
+    }
+    set_result_payload(args, payload)
+
+    if json_enabled(args):
+        print_json(payload)
+    else:
+        print(body)
+    return 0
+
+
+def edit_section_replace_command(args: argparse.Namespace, *, maybe_check_after: CheckAfter) -> int:
+    root = require_context_root(args.context)
+    dry_run = dry_run_enabled(args)
+    target = resolve_context_markdown_file(root, args.file)
+    updated = replace_section_text(target.read_text(encoding="utf-8"), args.heading, read_edit_input(args))
+    if not dry_run:
+        target.write_text(updated, encoding="utf-8")
+    check_result = maybe_check_after(args, root)
+    action = "would replace" if dry_run else "replaced"
+    return emit_write_result(
+        args,
+        "edit section replace",
+        f"{action} section {args.heading} in {target}",
+        [target],
+        check_result,
+    )
+
+
+def edit_section_append_command(args: argparse.Namespace, *, maybe_check_after: CheckAfter) -> int:
+    root = require_context_root(args.context)
+    dry_run = dry_run_enabled(args)
+    target = resolve_context_markdown_file(root, args.file)
+    updated = append_section_text(target.read_text(encoding="utf-8"), args.heading, read_edit_input(args))
+    if not dry_run:
+        target.write_text(updated, encoding="utf-8")
+    check_result = maybe_check_after(args, root)
+    action = "would append" if dry_run else "appended"
+    return emit_write_result(
+        args,
+        "edit section append",
+        f"{action} to section {args.heading} in {target}",
+        [target],
+        check_result,
+    )
+
+
+def edit_table_upsert_command(args: argparse.Namespace, *, maybe_check_after: CheckAfter) -> int:
+    root = require_context_root(args.context)
+    dry_run = dry_run_enabled(args)
+    target = resolve_context_markdown_file(root, args.file)
+    updated = upsert_table_row(
+        target.read_text(encoding="utf-8"),
+        args.header,
+        args.key_column,
+        args.key,
+        parse_cell_updates(args.cell),
+    )
+    if not dry_run:
+        target.write_text(updated, encoding="utf-8")
+    check_result = maybe_check_after(args, root)
+    action = "would upsert" if dry_run else "upserted"
+    return emit_write_result(
+        args,
+        "edit table upsert",
+        f"{action} table row {args.key} in {target}",
+        [target],
+        check_result,
+    )