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.
- promptmigrate/__init__.py +21 -0
- promptmigrate/__main__.py +3 -0
- promptmigrate/apply.py +116 -0
- promptmigrate/cli.py +123 -0
- promptmigrate/commands/__init__.py +5 -0
- promptmigrate/commands/check.py +65 -0
- promptmigrate/commands/current.py +25 -0
- promptmigrate/commands/diff.py +19 -0
- promptmigrate/commands/downgrade.py +36 -0
- promptmigrate/commands/env.py +35 -0
- promptmigrate/commands/get.py +48 -0
- promptmigrate/commands/history.py +41 -0
- promptmigrate/commands/init.py +43 -0
- promptmigrate/commands/plan.py +51 -0
- promptmigrate/commands/restamp.py +47 -0
- promptmigrate/commands/revision.py +97 -0
- promptmigrate/commands/upgrade.py +36 -0
- promptmigrate/commands/validate.py +96 -0
- promptmigrate/core.py +30 -0
- promptmigrate/draftdiff.py +41 -0
- promptmigrate/errors.py +91 -0
- promptmigrate/output.py +122 -0
- promptmigrate/plan.py +112 -0
- promptmigrate/project.py +160 -0
- promptmigrate/protocol/__init__.py +9 -0
- promptmigrate/protocol/equality.py +15 -0
- promptmigrate/protocol/jsonloader.py +92 -0
- promptmigrate/protocol/limits.py +9 -0
- promptmigrate/protocol/rules.py +80 -0
- promptmigrate/revisions.py +181 -0
- promptmigrate/secretscan.py +195 -0
- promptmigrate/store/__init__.py +13 -0
- promptmigrate/store/environments.py +181 -0
- promptmigrate/store/events.py +70 -0
- promptmigrate/store/lock.py +66 -0
- promptmigrate/store/sqlite.py +147 -0
- promptmigrate_cli-0.1.0.dist-info/METADATA +247 -0
- promptmigrate_cli-0.1.0.dist-info/RECORD +42 -0
- promptmigrate_cli-0.1.0.dist-info/WHEEL +5 -0
- promptmigrate_cli-0.1.0.dist-info/entry_points.txt +2 -0
- promptmigrate_cli-0.1.0.dist-info/licenses/LICENSE +21 -0
- 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
|
promptmigrate/errors.py
ADDED
|
@@ -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."""
|
promptmigrate/output.py
ADDED
|
@@ -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, ())
|