promptmigrate-cli 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (42) hide show
  1. promptmigrate/__init__.py +21 -0
  2. promptmigrate/__main__.py +3 -0
  3. promptmigrate/apply.py +116 -0
  4. promptmigrate/cli.py +123 -0
  5. promptmigrate/commands/__init__.py +5 -0
  6. promptmigrate/commands/check.py +65 -0
  7. promptmigrate/commands/current.py +25 -0
  8. promptmigrate/commands/diff.py +19 -0
  9. promptmigrate/commands/downgrade.py +36 -0
  10. promptmigrate/commands/env.py +35 -0
  11. promptmigrate/commands/get.py +48 -0
  12. promptmigrate/commands/history.py +41 -0
  13. promptmigrate/commands/init.py +43 -0
  14. promptmigrate/commands/plan.py +51 -0
  15. promptmigrate/commands/restamp.py +47 -0
  16. promptmigrate/commands/revision.py +97 -0
  17. promptmigrate/commands/upgrade.py +36 -0
  18. promptmigrate/commands/validate.py +96 -0
  19. promptmigrate/core.py +30 -0
  20. promptmigrate/draftdiff.py +41 -0
  21. promptmigrate/errors.py +91 -0
  22. promptmigrate/output.py +122 -0
  23. promptmigrate/plan.py +112 -0
  24. promptmigrate/project.py +160 -0
  25. promptmigrate/protocol/__init__.py +9 -0
  26. promptmigrate/protocol/equality.py +15 -0
  27. promptmigrate/protocol/jsonloader.py +92 -0
  28. promptmigrate/protocol/limits.py +9 -0
  29. promptmigrate/protocol/rules.py +80 -0
  30. promptmigrate/revisions.py +181 -0
  31. promptmigrate/secretscan.py +195 -0
  32. promptmigrate/store/__init__.py +13 -0
  33. promptmigrate/store/environments.py +181 -0
  34. promptmigrate/store/events.py +70 -0
  35. promptmigrate/store/lock.py +66 -0
  36. promptmigrate/store/sqlite.py +147 -0
  37. promptmigrate_cli-0.1.0.dist-info/METADATA +247 -0
  38. promptmigrate_cli-0.1.0.dist-info/RECORD +42 -0
  39. promptmigrate_cli-0.1.0.dist-info/WHEEL +5 -0
  40. promptmigrate_cli-0.1.0.dist-info/entry_points.txt +2 -0
  41. promptmigrate_cli-0.1.0.dist-info/licenses/LICENSE +21 -0
  42. promptmigrate_cli-0.1.0.dist-info/top_level.txt +1 -0
@@ -0,0 +1,47 @@
1
+ """`restamp`: accept line-ending-only changes to applied v0 revisions by re-stamping their ledger checksums."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import argparse
6
+ from pathlib import Path
7
+
8
+ from .. import apply, output, revisions, store
9
+ from ..store import events
10
+
11
+
12
+ def restamp(project_dir: Path, env: str) -> list[str]:
13
+ """Re-stamp each applied v0 row whose file differs only in line endings (ADR-027); all or nothing.
14
+
15
+ Any other mismatch raises the normal IntegrityError and nothing is written. Each re-stamped row appends a
16
+ `restamp` event (ADR-029).
17
+ """
18
+ env = store.resolve_environment(project_dir, env)
19
+ revisions_ = revisions.load_revisions(project_dir)
20
+ with store._project_lock(project_dir):
21
+ if not store._db_path(project_dir, env).exists():
22
+ return [] # base state: nothing is applied, so nothing is re-stamped and no state file is created
23
+ with store.connect_write(project_dir, env) as db:
24
+ db.execute("BEGIN IMMEDIATE")
25
+ stale = apply.line_ending_only(db, revisions_)
26
+ if stale:
27
+ events.ensure(db) # adopts an old DB in this transaction; skipped on a no-op (ADR-029)
28
+ old = dict(apply._applied(db))
29
+ for r in stale:
30
+ db.execute("UPDATE applied_revisions SET checksum=? WHERE revision=?", (r.checksum, r.revision))
31
+ events.record(db, "restamp", r.revision, r.checksum, old[r.revision])
32
+ apply._verify(db, revisions_, env)
33
+ return [r.revision for r in stale]
34
+
35
+
36
+ def execute(args: argparse.Namespace) -> output.Result:
37
+ """Run `restamp` and return its text and JSON result."""
38
+ project_dir = Path(args.project)
39
+ label = store.display_name(project_dir, args.env)
40
+ ids = restamp(project_dir, args.env)
41
+ text = f"Restamped {len(ids)} revision(s) in {label}: {', '.join(ids) or '(none)'}\n"
42
+ return output.Result("restamp", {"restamped": ids}, text, label)
43
+
44
+
45
+ def run(args: argparse.Namespace) -> None:
46
+ """Run `restamp` and print its text output."""
47
+ output.emit_result(execute(args), "text", [])
@@ -0,0 +1,97 @@
1
+ """`revision`: write a new revision file from the drafts' difference to the source head."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import argparse
6
+ import re
7
+ import uuid
8
+ import warnings
9
+ from datetime import datetime, timezone
10
+ from pathlib import Path
11
+
12
+ from .. import draftdiff, output, project, protocol, revisions, secretscan
13
+ from ..errors import LegacyRevisionWarning, SchemaError, SecretDetectedError, SecretInHistoryWarning, StorageError
14
+ from ..store import lock
15
+
16
+ _ID_ATTEMPTS = 5
17
+
18
+
19
+ def _new_id(taken: set[str]) -> str:
20
+ """A fresh 12-hex revision id that is not already in history."""
21
+ for _ in range(_ID_ATTEMPTS):
22
+ rid = uuid.uuid4().hex[:12]
23
+ if rid not in taken:
24
+ return rid
25
+ raise StorageError(f"Could not generate a unique revision id after {_ID_ATTEMPTS} attempts")
26
+
27
+
28
+ def revision(project_dir: Path, message: str) -> revisions.Revision:
29
+ if not message.strip():
30
+ raise SchemaError("Revision message cannot be empty")
31
+ # History is read inside the lock, so two concurrent `revision` calls serialize and the second one diffs against
32
+ # the first one's new head (I18).
33
+ with lock._project_lock(project_dir):
34
+ return _write_revision(project_dir, message)
35
+
36
+
37
+ def _write_revision(project_dir: Path, message: str) -> revisions.Revision:
38
+ all_revisions = revisions.load_revisions(project_dir)
39
+ changes = draftdiff.draft_diff(project_dir)
40
+ if not changes:
41
+ raise SchemaError("No changes between drafts and migration head")
42
+ rid = _new_id({r.revision for r in all_revisions})
43
+ parent = all_revisions[-1].revision if all_revisions else None
44
+ for name, change in changes.items():
45
+ if change["after"] is not None:
46
+ found = protocol.config_violations(name, change["after"])
47
+ if found:
48
+ raise SchemaError(f"New revision would be invalid: {', '.join(found)}")
49
+ allow = project.load_allowlist(project_dir)
50
+ findings = [finding for name, change in changes.items() if change["after"] is not None
51
+ for finding in secretscan.scan(name, change["after"], allow)]
52
+ findings += secretscan.scan("(message)", {"message": message.strip()}, allow)
53
+ if findings:
54
+ raise SecretDetectedError(findings)
55
+ item = {
56
+ "format_version": 1,
57
+ "revision": rid,
58
+ "down_revision": parent,
59
+ "message": message.strip(),
60
+ "created_at": datetime.now(timezone.utc).isoformat(),
61
+ "changes": changes,
62
+ }
63
+ text = project.pretty(item)
64
+ # write_new_file writes these UTF-8 bytes with LF line endings on every OS (ADR-026), so this is its exact size.
65
+ size = len(text.encode("utf-8"))
66
+ if size > protocol.limits.MAX_REVISION_BYTES:
67
+ raise SchemaError(f"New revision would be {size} bytes; the limit is {protocol.limits.MAX_REVISION_BYTES}")
68
+ for name, change in changes.items():
69
+ if change["before"] is not None:
70
+ carried = protocol.config_violations(name, change["before"])
71
+ if carried:
72
+ warnings.warn(f"revision {rid}: {name} before carries {', '.join(carried)} from history "
73
+ "(copied for compatibility)", LegacyRevisionWarning, stacklevel=3)
74
+ for name, change in changes.items():
75
+ if change["before"] is not None:
76
+ for finding in secretscan.scan(name, change["before"], allow):
77
+ warnings.warn(f"{finding.name} {finding.path} {finding.rule} copied from history into before; "
78
+ "the credential must be rotated", SecretInHistoryWarning, stacklevel=3)
79
+ root = project.require_init(project_dir)
80
+ path = root / "versions" / f"{rid}_{re.sub(r'[^a-z0-9]+', '_', message.lower()).strip('_')[:50] or 'revision'}.json"
81
+ try:
82
+ project.write_new_file(path, text)
83
+ except FileExistsError:
84
+ raise StorageError(f"Revision file already exists: {path.name}") from None
85
+ return revisions.load_revisions(project_dir)[-1]
86
+
87
+
88
+ def execute(args: argparse.Namespace) -> output.Result:
89
+ """Run `revision` and return its text and JSON result."""
90
+ r = revision(Path(args.project), args.message)
91
+ data = {"revision": r.revision, "down_revision": r.down_revision, "message": r.message, "path": str(r.path)}
92
+ return output.Result("revision", data, f"Created {r.revision} (parent: {r.down_revision or 'base'}): {r.path}\n")
93
+
94
+
95
+ def run(args: argparse.Namespace) -> None:
96
+ """Run `revision` and print its text output."""
97
+ output.emit_result(execute(args), "text", [])
@@ -0,0 +1,36 @@
1
+ """`upgrade`: apply pending revisions to an environment, up to head or a target revision."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import argparse
6
+ from pathlib import Path
7
+
8
+ from .. import apply, output, plan, revisions, store
9
+
10
+
11
+ def upgrade(project_dir: Path, env: str, target: str = "head") -> list[str]:
12
+ env = store.resolve_environment(project_dir, env)
13
+ revisions_ = revisions.load_revisions(project_dir)
14
+ target_count = plan.upgrade_count(revisions_, target)
15
+ with store.connect_write(project_dir, env) as db:
16
+ db.execute("BEGIN IMMEDIATE")
17
+ applied_count = apply._verify(db, revisions_, env)
18
+ steps = plan.upgrade_steps(revisions_, applied_count, target_count)
19
+ apply.migrate(db, steps)
20
+ store.adopt_environments(project_dir)
21
+ return [r.revision for r in steps]
22
+
23
+
24
+ def execute(args: argparse.Namespace) -> output.Result:
25
+ """Run `upgrade` and return its text and JSON result."""
26
+ project_dir = Path(args.project)
27
+ label = store.display_name(project_dir, args.env)
28
+ ids = upgrade(project_dir, args.env, args.target)
29
+ data = {"direction": "up", "target": args.target, "revisions": ids}
30
+ text = f"{label}: applied {len(ids)} revision(s): {', '.join(ids) or '(already current)'}\n"
31
+ return output.Result("upgrade", data, text, label)
32
+
33
+
34
+ def run(args: argparse.Namespace) -> None:
35
+ """Run `upgrade` and print its text output."""
36
+ output.emit_result(execute(args), "text", [])
@@ -0,0 +1,96 @@
1
+ """`validate`: check every source file (history, drafts, manifest, allowlist) without touching environment state."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import argparse
6
+ import warnings
7
+ from pathlib import Path
8
+ from typing import Any
9
+
10
+ from .. import draftdiff, output, project, protocol, revisions, store
11
+ from ..errors import MigrationConflictError, SchemaError, StrictValidationError
12
+ from .check import audit_secrets
13
+
14
+
15
+ def validate(project_dir: Path, strict: bool = False, drafts_clean: bool = False) -> dict[str, Any]:
16
+ """Validate source only (ADR-028); never resolves an environment or reads anything under `states/` (I19)."""
17
+ root = project.require_init(project_dir)
18
+ states_dir = root / "states"
19
+ # Guard: a revision symlink that resolves under states/ would make validate read applied state.
20
+ for path in sorted((root / "versions").glob("*.json")):
21
+ try:
22
+ if path.resolve().is_relative_to(states_dir.resolve()):
23
+ raise SchemaError(f"Invalid revision {path.name}: resolves under states/")
24
+ except (RuntimeError, OSError):
25
+ # A symlink loop or unreadable path cannot resolve under states/; the loader will report it.
26
+ pass
27
+
28
+ caught: list[warnings.WarningMessage] = []
29
+ try:
30
+ with warnings.catch_warnings(record=True) as caught:
31
+ warnings.simplefilter("always")
32
+ try:
33
+ revisions_ = revisions.load_revisions(project_dir)
34
+ except MigrationConflictError as exc:
35
+ # A source-history replay conflict is a tier-A source error for `validate`: exit 3, not 4.
36
+ raise SchemaError(f"Invalid source history: {exc}") from exc
37
+ project.read_drafts(project_dir)
38
+ # Without a manifest, read_environments infers declarations from states/, which validate must never read.
39
+ # Read the manifest only when present; never fall back to states/ inference (I19).
40
+ manifest = root / "environments.json"
41
+ if manifest.exists() or manifest.is_symlink():
42
+ _read_manifest_only(manifest, root)
43
+ project.load_allowlist(project_dir)
44
+ audit_secrets(project_dir)
45
+ changed = sorted(draftdiff.draft_diff(project_dir)) if drafts_clean else []
46
+ finally:
47
+ for w in caught: # re-emit, so the CLI still prints or lists them even on partial failure
48
+ warnings.warn_explicit(w.message, w.category, w.filename, w.lineno)
49
+ if changed:
50
+ raise SchemaError(f"Drafts differ from head: {', '.join(changed)}")
51
+ count = len(output.collect_warnings(caught))
52
+ if strict and count:
53
+ raise StrictValidationError(f"validate --strict: {count} warning(s)")
54
+ versions = {"0": 0, "1": 0}
55
+ for r in revisions_:
56
+ versions[str(r.format_version)] += 1
57
+ return {
58
+ "revisions": len(revisions_),
59
+ "head": revisions_[-1].revision if revisions_ else None,
60
+ "format_versions": versions,
61
+ "drafts_clean": True if drafts_clean else None,
62
+ }
63
+
64
+
65
+ def _read_manifest_only(manifest: Path, root: Path) -> None:
66
+ """Read `environments.json` without falling back to states/ inference (I19).
67
+
68
+ Mirrors the structural validation of store.read_environments but never calls _infer_environments,
69
+ so a concurrently removed manifest cannot make validate enumerate states/.
70
+ """
71
+ value, _raw, _rules = protocol.load_json(manifest, kind="environments", root=root)
72
+ if not isinstance(value, dict) or set(value) != {"environments"} or not isinstance(value["environments"], dict):
73
+ raise SchemaError("Invalid environments file: expected exactly {'environments': object}")
74
+ environments = value["environments"]
75
+ for name, metadata in environments.items():
76
+ protocol.rules.validate_environment_name(name)
77
+ if not isinstance(metadata, dict):
78
+ raise SchemaError(f"Invalid environments file: metadata for {name!r} must be an object")
79
+ if protocol.config_depth(metadata) > protocol.limits.MAX_CONFIG_DEPTH:
80
+ raise SchemaError(f"Invalid environments file: metadata for {name!r} exceeds depth limit")
81
+ collisions = protocol.case_collisions(environments)
82
+ if collisions:
83
+ raise SchemaError(f"Invalid environments file: case-collision {collisions[0]}")
84
+
85
+
86
+ def execute(args: argparse.Namespace) -> output.Result:
87
+ """Run `validate` and return its text and JSON result."""
88
+ data = validate(Path(args.project), args.strict, args.drafts_clean)
89
+ v = data["format_versions"]
90
+ text = f"OK: {data['revisions']} revisions (v0: {v['0']}, v1: {v['1']}), head {data['head'] or 'base'}\n"
91
+ return output.Result("validate", data, text)
92
+
93
+
94
+ def run(args: argparse.Namespace) -> None:
95
+ """Run `validate` and print its text output."""
96
+ output.emit_result(execute(args), "text", [])
promptmigrate/core.py ADDED
@@ -0,0 +1,30 @@
1
+ """Public facade: every name the original monolithic core.py exposed, re-exported from the module that defines it.
2
+
3
+ New code imports from the defining module. Monkeypatching a name here has no effect on behaviour; patch the defining
4
+ module instead (see docs/DECISIONS.md, ADR-022).
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ from .apply import _actual, _applied, _verify
10
+ from .commands.check import audit_secrets, check
11
+ from .commands.downgrade import downgrade
12
+ from .commands.env import env_add, env_list
13
+ from .commands.get import get_config, redacted_config
14
+ from .commands.history import redacted_history
15
+ from .commands.init import init
16
+ from .commands.plan import plan
17
+ from .commands.restamp import restamp
18
+ from .commands.revision import revision
19
+ from .commands.upgrade import upgrade
20
+ from .commands.validate import validate
21
+ from .draftdiff import draft_diff, redacted_diff
22
+ from .errors import (
23
+ DriftError, InitializationError, IntegrityError, LegacyRevisionWarning, MigrationConflictError, MigrationError,
24
+ PendingRevisionsError, RevisionGraphError, SchemaError, SecretDetectedError, SecretInHistoryWarning,
25
+ SecretRedactedWarning, StaleAllowlistWarning, StorageError, StrictValidationError, TargetError,
26
+ )
27
+ from .project import ALLOWLIST_FILE, load_allowlist, pretty, read_drafts, require_init, root_dir
28
+ from .protocol import canonical, same
29
+ from .revisions import _LEGACY, Revision, _apply_changes, _hash, load_revisions, replay_revisions
30
+ from .secretscan import _REDACTED
@@ -0,0 +1,41 @@
1
+ """Drafts compared with the replayed source head (never with an environment)."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import warnings
6
+ from pathlib import Path
7
+ from typing import Any
8
+
9
+ from . import project, protocol, revisions, secretscan
10
+ from .errors import SecretRedactedWarning
11
+
12
+
13
+ def draft_diff(project_dir: Path) -> dict[str, dict[str, Any]]:
14
+ expected = revisions.replay_revisions(revisions.load_revisions(project_dir))
15
+ wanted = project.read_drafts(project_dir)
16
+ return {
17
+ name: {"before": expected.get(name), "after": wanted.get(name)}
18
+ for name in sorted(expected.keys() | wanted.keys())
19
+ if not protocol.same(expected.get(name), wanted.get(name))
20
+ }
21
+
22
+
23
+ def redacted_diff(project_dir: Path) -> tuple[dict[str, dict[str, Any]], list[dict[str, str]]]:
24
+ """draft_diff() for display: secret-like values replaced by "<redacted:RULE>", plus what was redacted.
25
+
26
+ Redacted output is not a config source: never feed it back into a draft or an application.
27
+ """
28
+ allow = project.load_allowlist(project_dir)
29
+ changes, redacted = {}, []
30
+ for name, change in draft_diff(project_dir).items():
31
+ sides = {}
32
+ for side in ("before", "after"):
33
+ value = change[side]
34
+ if value is not None:
35
+ value, paths = secretscan.redact(name, value, allow)
36
+ redacted += [{"name": name, "side": side, "path": path} for path in paths]
37
+ sides[side] = value
38
+ changes[name] = sides
39
+ if redacted:
40
+ warnings.warn(secretscan._REDACTED.format(count=len(redacted)), SecretRedactedWarning, stacklevel=2)
41
+ return changes, redacted
@@ -0,0 +1,91 @@
1
+ """Error and warning types. Every handled error is a MigrationError; every warning is a PromptMigrateWarning."""
2
+
3
+
4
+ class MigrationError(Exception):
5
+ """An invalid revision, unexpected environment state, or unsafe operation."""
6
+
7
+
8
+ class InitializationError(MigrationError):
9
+ """The project is not initialized, or is already initialized."""
10
+
11
+
12
+ class SchemaError(MigrationError):
13
+ """A draft, revision file or command input is malformed or breaks a validation rule."""
14
+
15
+
16
+ class StrictValidationError(SchemaError):
17
+ """`validate --strict` saw at least one warning."""
18
+
19
+
20
+ class EnvironmentNotDeclaredError(MigrationError):
21
+ """The requested environment is not present in the declared environment manifest."""
22
+
23
+ def __init__(self, env: str) -> None:
24
+ self.env = env
25
+ super().__init__(f"Environment {env!r} is not declared; declare it with `promptmigrate env add {env}`.")
26
+
27
+
28
+ class StorageError(MigrationError):
29
+ """The local environment state database is missing required storage or is otherwise unusable."""
30
+
31
+
32
+ class SecretDetectedError(SchemaError):
33
+ """New revision content holds a secret-like value that is not allowlisted. Carries findings, never values."""
34
+
35
+ def __init__(self, findings) -> None:
36
+ self.findings = [{"name": f.name, "path": f.path, "rule": f.rule} for f in findings]
37
+ listed = "; ".join(f"{f['name']} {f['path']} {f['rule']}" for f in self.findings)
38
+ super().__init__(f"Secret-like values in new revision content: {listed}. "
39
+ "No file was written; remove them or allowlist a reviewed false positive.")
40
+
41
+
42
+ class RevisionGraphError(MigrationError):
43
+ """Source history is not one linear chain: duplicate id, several roots, missing parent, branch or cycle."""
44
+
45
+
46
+ class MigrationConflictError(MigrationError):
47
+ """A change's precondition does not match the state it is applied to."""
48
+
49
+
50
+ class DriftError(MigrationError):
51
+ """An environment's stored configs differ from the replay of its applied revisions."""
52
+
53
+
54
+ class IntegrityError(MigrationError):
55
+ """An environment's ledger does not match source history: an edited, missing or diverging revision."""
56
+
57
+
58
+ class TargetError(MigrationError):
59
+ """The requested revision target or config name does not exist, or is in the wrong direction."""
60
+
61
+
62
+ class PendingRevisionsError(MigrationError):
63
+ """The environment is behind head where head was required."""
64
+
65
+
66
+ class PromptMigrateWarning(UserWarning):
67
+ """Base class of every warning PromptMigrate emits."""
68
+
69
+
70
+ class ProductionNameWarning(PromptMigrateWarning):
71
+ """A production-like environment name still refers only to local SQLite state."""
72
+
73
+
74
+ class EnvironmentAdoptionWarning(PromptMigrateWarning):
75
+ """A legacy workspace is being adopted into the declared environment manifest."""
76
+
77
+
78
+ class LegacyRevisionWarning(PromptMigrateWarning):
79
+ """An existing revision file breaks a tier-B rule; it is accepted for compatibility."""
80
+
81
+
82
+ class SecretRedactedWarning(PromptMigrateWarning):
83
+ """Secret-like values were redacted from this command's output."""
84
+
85
+
86
+ class SecretInHistoryWarning(PromptMigrateWarning):
87
+ """A secret-like value is in committed history; it stays in Git and must be rotated."""
88
+
89
+
90
+ class StaleAllowlistWarning(PromptMigrateWarning):
91
+ """A secret allowlist entry matched nothing in drafts or history."""
@@ -0,0 +1,122 @@
1
+ """Output rendering and the error -> exit code table.
2
+
3
+ Commands build a `Result` (a JSON-safe `data` dict plus the exact text they print today) and know nothing about
4
+ formats. This module renders it as text or as one JSON envelope and owns the exit-code mapping, so a new command only
5
+ needs an `execute(args) -> Result`. Envelope schema: `promptmigrate.output/1` (docs/CLI_SPEC.md).
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import json
11
+ import sqlite3
12
+ import sys
13
+ import warnings
14
+ from dataclasses import dataclass
15
+ from pathlib import Path
16
+ from typing import Any
17
+
18
+ from . import errors, store
19
+
20
+ SCHEMA = "promptmigrate.output/1"
21
+ FORMATS = ("text", "json")
22
+
23
+ # Most specific class first: the first isinstance match wins. (class, exit code, JSON error name)
24
+ _TABLE: tuple[tuple[type[BaseException], int, str], ...] = (
25
+ (errors.SchemaError, 3, "schema"), # includes SecretDetectedError
26
+ (errors.RevisionGraphError, 3, "schema"),
27
+ (errors.DriftError, 4, "conflict"),
28
+ (errors.IntegrityError, 4, "conflict"),
29
+ (errors.MigrationConflictError, 4, "conflict"),
30
+ (errors.StorageError, 5, "storage"),
31
+ (sqlite3.Error, 5, "storage"),
32
+ (OSError, 5, "storage"),
33
+ (errors.MigrationError, 1, "error"), # uninitialized, undeclared env, target, pending, anything else
34
+ )
35
+ HANDLED = (errors.MigrationError, OSError, sqlite3.Error)
36
+
37
+
38
+ @dataclass
39
+ class Result:
40
+ """What a command produced: `text` is the exact stdout of text mode, `data` the JSON payload."""
41
+ command: str
42
+ data: dict[str, Any]
43
+ text: str = ""
44
+ env: str | None = None
45
+
46
+
47
+ @dataclass
48
+ class Warned:
49
+ """A PromptMigrate warning as listed in JSON output."""
50
+ category: str
51
+ message: str
52
+
53
+
54
+ def exit_code_for(exc: BaseException) -> int:
55
+ """The process exit code for a handled error (1, 3, 4 or 5)."""
56
+ for cls, code, _name in _TABLE:
57
+ if isinstance(exc, cls):
58
+ return code
59
+ raise TypeError(f"unhandled exception type: {type(exc).__name__}")
60
+
61
+
62
+ def error_name_for(exc: BaseException) -> str:
63
+ """The `error.code` name used in the JSON envelope for a handled error."""
64
+ for cls, _code, name in _TABLE:
65
+ if isinstance(exc, cls):
66
+ return name
67
+ raise TypeError(f"unhandled exception type: {type(exc).__name__}")
68
+
69
+
70
+ def describe(args: Any) -> tuple[str, str | None]:
71
+ """(command name, environment) of a parsed command line, for an error envelope; `env` has no --env of its own."""
72
+ if getattr(args, "env_command", None):
73
+ return f"env {args.env_command}", None
74
+ env = getattr(args, "env", None)
75
+ if env is not None:
76
+ try:
77
+ env = store.display_name(Path(args.project), env)
78
+ except Exception: # an unreadable manifest or invalid name was already reported; keep what was typed
79
+ pass
80
+ return args.command, env
81
+
82
+
83
+ def collect_warnings(caught: list[warnings.WarningMessage]) -> list[Warned]:
84
+ """Each distinct PromptMigrate warning once, in first-seen order."""
85
+ seen, result = set(), []
86
+ for w in caught:
87
+ if issubclass(w.category, errors.PromptMigrateWarning):
88
+ key = (w.category, str(w.message))
89
+ if key not in seen:
90
+ seen.add(key)
91
+ result.append(Warned(w.category.__name__, str(w.message)))
92
+ return result
93
+
94
+
95
+ def _dump(doc: dict[str, Any]) -> str:
96
+ """One JSON document on one line, newline-terminated; non-finite numbers are rejected."""
97
+ return json.dumps(doc, ensure_ascii=True, allow_nan=False) + "\n"
98
+
99
+
100
+ def emit_result(result: Result, fmt: str, warned: list[Warned]) -> None:
101
+ """Print a success. In text mode the warnings are the caller's business (stderr)."""
102
+ if fmt == "json":
103
+ sys.stdout.write(_dump({
104
+ "schema": SCHEMA, "ok": True, "command": result.command, "env": result.env,
105
+ "data": result.data, "warnings": [vars(w) for w in warned],
106
+ }))
107
+ else:
108
+ sys.stdout.write(result.text)
109
+
110
+
111
+ def emit_error(exc: BaseException, fmt: str, command: str, env: str | None, warned: list[Warned]) -> int:
112
+ """Print a handled error: `Error: …` on stderr in text mode, an envelope on stdout in JSON mode. Returns the code."""
113
+ code = exit_code_for(exc)
114
+ if fmt == "json":
115
+ sys.stdout.write(_dump({
116
+ "schema": SCHEMA, "ok": False, "command": command, "env": env,
117
+ "error": {"code": error_name_for(exc), "exit_code": code, "message": str(exc)},
118
+ "warnings": [vars(w) for w in warned],
119
+ }))
120
+ else:
121
+ print(f"Error: {exc}", file=sys.stderr)
122
+ return code
promptmigrate/plan.py ADDED
@@ -0,0 +1,112 @@
1
+ """Pure migration planning: resolve a target against source history and the applied count. No I/O.
2
+
3
+ `upgrade`, `downgrade` and `plan` all resolve targets here, so a preview cannot disagree with what is applied.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ from dataclasses import dataclass
9
+
10
+ from . import protocol
11
+ from .errors import TargetError
12
+ from .revisions import Revision
13
+
14
+
15
+ @dataclass(frozen=True)
16
+ class Step:
17
+ """One revision to apply (or revert) and the config changes it makes, as sorted (name, kind) pairs."""
18
+ revision: str
19
+ changes: tuple[tuple[str, str], ...]
20
+
21
+
22
+ @dataclass(frozen=True)
23
+ class MigrationPlan:
24
+ """direction is "upgrade", "downgrade" or "none"; start and target are revision ids, None meaning base."""
25
+ direction: str
26
+ start: str | None
27
+ target: str | None
28
+ steps: tuple[Step, ...]
29
+
30
+
31
+ def _unknown(target: str) -> TargetError:
32
+ """The error every command raises for a target that is not a revision id."""
33
+ return TargetError(f"Unknown target revision: {target}")
34
+
35
+
36
+ def upgrade_count(revisions: list[Revision], target: str) -> int:
37
+ """Number of revisions that should be applied once `target` (`head` or a revision id) is reached."""
38
+ ids = [r.revision for r in revisions]
39
+ if target == "head":
40
+ return len(ids)
41
+ if target not in ids:
42
+ raise _unknown(target)
43
+ return ids.index(target) + 1
44
+
45
+
46
+ def upgrade_steps(revisions: list[Revision], applied: int, target_count: int) -> list[Revision]:
47
+ """The revisions to apply, oldest first; a target behind the current position is an error."""
48
+ if applied > target_count:
49
+ raise TargetError("Upgrade target is behind current revision; use downgrade")
50
+ return revisions[applied:target_count]
51
+
52
+
53
+ def downgrade_count(revisions: list[Revision], applied: int, target: str) -> int:
54
+ """Number of revisions that should remain applied after reverting to `target` (`-1`, `base` or a revision id)."""
55
+ ids = [r.revision for r in revisions]
56
+ if target == "-1":
57
+ return max(0, applied - 1)
58
+ if target == "base":
59
+ return 0
60
+ if target in ids:
61
+ return ids.index(target) + 1
62
+ raise _unknown(target)
63
+
64
+
65
+ def downgrade_steps(revisions: list[Revision], applied: int, target_count: int) -> list[Revision]:
66
+ """The revisions to revert, newest first; a target ahead of the current position is an error."""
67
+ if target_count > applied:
68
+ raise TargetError("Downgrade target is ahead of current revision; use upgrade")
69
+ return list(reversed(revisions[target_count:applied]))
70
+
71
+
72
+ def _kind(old, new) -> str:
73
+ """Classify one config change by its from and to values: create, update, delete or unchanged."""
74
+ if old is None:
75
+ return "create" if new is not None else "unchanged"
76
+ if new is None:
77
+ return "delete"
78
+ return "unchanged" if protocol.same(old, new) else "update"
79
+
80
+
81
+ def _step(revision: Revision, backward: bool) -> Step:
82
+ """One revision as a plan step; a backward step swaps before and after."""
83
+ old, new = ("after", "before") if backward else ("before", "after")
84
+ return Step(revision.revision, tuple(
85
+ (name, _kind(change[old], change[new])) for name, change in sorted(revision.changes.items())
86
+ ))
87
+
88
+
89
+ def _id(revisions: list[Revision], count: int) -> str | None:
90
+ """The id of the newest of the first `count` revisions, or None for base."""
91
+ return revisions[count - 1].revision if count else None
92
+
93
+
94
+ def build(revisions: list[Revision], applied: int, target: str) -> MigrationPlan:
95
+ """Plan the move from `applied` revisions to `target`; the direction follows from where the target lies.
96
+
97
+ `head` and later revisions upgrade; `-1`, `base` and earlier revisions downgrade; the current position is a no-op.
98
+ """
99
+ if target == "head":
100
+ count = len(revisions)
101
+ elif target in ("-1", "base"):
102
+ count = downgrade_count(revisions, applied, target)
103
+ else:
104
+ count = upgrade_count(revisions, target)
105
+ start = _id(revisions, applied)
106
+ if count > applied:
107
+ steps = tuple(_step(r, False) for r in upgrade_steps(revisions, applied, count))
108
+ return MigrationPlan("upgrade", start, _id(revisions, count), steps)
109
+ if count < applied:
110
+ steps = tuple(_step(r, True) for r in downgrade_steps(revisions, applied, count))
111
+ return MigrationPlan("downgrade", start, _id(revisions, count), steps)
112
+ return MigrationPlan("none", start, start, ())