trueppm-api 0.4.0b2__py3-none-any.whl

trueppm_api/apps/projects/management/commands/export_program.py

@@ -0,0 +1,50 @@
+"""Export a program to canonical JSON seed format (ADR-0109, issue #616).
+
+Usage::
+
+    python manage.py export_program <slug> [--out <path>]
+
+``<slug>`` matches ``Program.code``. Writes to ``--out`` if given, else stdout.
+The output round-trips: re-importing it reproduces the program.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from django.core.management.base import BaseCommand, CommandError
+
+from trueppm_api.apps.projects.models import Program
+from trueppm_api.apps.projects.seed.exporter import dump_seed, export_program
+
+
+class Command(BaseCommand):
+    help = "Export a TruePPM program to a canonical JSON seed file."
+
+    def add_arguments(self, parser: Any) -> None:
+        parser.add_argument("slug", help="Program slug (Program.code).")
+        parser.add_argument("--out", help="Output file path. Defaults to stdout.")
+        parser.add_argument(
+            "--with-events",
+            action="store_true",
+            help=(
+                "Emit a v2 seed (ADR-0114 §7 / #1109): anchor-relative dates plus a "
+                "reconstructed events timeline, so the export re-imports as the program's "
+                "dated life. Default is v1 final-state (byte-identical round-trip, #616)."
+            ),
+        )
+
+    def handle(self, *args: Any, **options: Any) -> None:
+        slug = options["slug"]
+        program = Program.objects.filter(code=slug, is_deleted=False).first()
+        if program is None:
+            raise CommandError(f"No live program with slug {slug!r}.")
+
+        body = dump_seed(export_program(program, with_events=bool(options.get("with_events"))))
+        out = options.get("out")
+        if out:
+            with open(out, "w", encoding="utf-8") as fh:
+                fh.write(body)
+            self.stdout.write(self.style.SUCCESS(f"Exported program {slug!r} to {out}"))
+        else:
+            self.stdout.write(body)

trueppm_api/apps/projects/management/commands/import_seed.py

@@ -0,0 +1,165 @@
+"""Import a canonical JSON seed file (ADR-0109, issue #615).
+
+Usage::
+
+    python manage.py import_seed <path> [--owner <username>] [--create-users]
+    python manage.py import_seed <path> --check
+
+Loads a seed document into the database via ``import_seed``. Re-running with the
+same file rebuilds the program subtree idempotently on the program slug; note
+that imported resources are created fresh each run (not deduplicated by email),
+so re-import can accumulate global resource rows — the deliberate cost of never
+rebinding a pre-existing resource into the importer's program (#1004).
+``--create-users`` mints any accounts the seed references that do not yet exist
+(intended for ``make seed`` and local demos, not production).
+
+``--check`` is the dry run (#2418): validate the file, print every diagnostic,
+exit 0/1, and touch neither the database nor the program slug the document
+names. Because the import is wipe-then-recreate on that slug (ADR-0109), this
+is how an operator answers *"will this be accepted?"* before pointing a
+destructive operation at a live program.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from django.contrib.auth import get_user_model
+from django.core.management.base import BaseCommand, CommandError
+
+from trueppm_api.apps.projects.models import Project
+from trueppm_api.apps.projects.seed import SeedValidationError, import_seed, inspect_seed
+from trueppm_api.apps.projects.seed.importer import SeedReplaceAmbiguous, SeedReplaceRequired
+
+User = get_user_model()
+
+
+class Command(BaseCommand):
+    help = "Import a TruePPM JSON seed file into the database, or --check it without importing."
+
+    def add_arguments(self, parser: Any) -> None:
+        parser.add_argument("path", help="Path to the JSON seed file.")
+        parser.add_argument(
+            "--owner",
+            help="Username to own the imported program. Defaults to the first superuser.",
+        )
+        parser.add_argument(
+            "--create-users",
+            action="store_true",
+            help="Create accounts referenced by the seed if they do not exist.",
+        )
+        parser.add_argument(
+            "--no-replace",
+            action="store_true",
+            help=(
+                "Refuse to import when a live program you own already holds this "
+                "seed's slug, instead of replacing it. The REST endpoint defaults "
+                "to refusing; this command defaults to replacing, because re-running "
+                "`make seed` in place is its whole job and an operator at a shell "
+                "has --check available to look first (ADR-0726)."
+            ),
+        )
+        parser.add_argument(
+            "--check",
+            action="store_true",
+            help=(
+                "Validate the file and report every problem without importing it. "
+                "Exits 1 if the document is invalid. Writes nothing."
+            ),
+        )
+
+    def handle(self, *args: Any, **options: Any) -> None:
+        path = options["path"]
+        try:
+            with open(path, encoding="utf-8") as fh:
+                payload = json.load(fh)
+        except FileNotFoundError as exc:
+            raise CommandError(f"Seed file not found: {path}") from exc
+        except json.JSONDecodeError as exc:
+            raise CommandError(f"Seed file is not valid JSON: {exc}") from exc
+
+        if options["check"]:
+            self._check(path, payload)
+            return
+
+        # Owner resolution is deliberately *after* the --check branch: a dry run
+        # must work on an instance with no superuser (a self-hoster validating a
+        # file before the first real import), and resolving an owner it would
+        # never use would fail that case for no reason.
+        owner = self._resolve_owner(options.get("owner"))
+
+        try:
+            program = import_seed(
+                payload,
+                owner=owner,
+                create_users=options["create_users"],
+                replace=not options["no_replace"],
+            )
+        except SeedValidationError as exc:
+            # Surface every validation error, one per line, then fail.
+            raise CommandError(str(exc)) from exc
+        except SeedReplaceRequired as exc:
+            raise CommandError(
+                f"{exc} Re-run without --no-replace to replace it (its projects move "
+                "to Trash), or edit the seed's program.slug."
+            ) from exc
+        except SeedReplaceAmbiguous as exc:
+            # Reachable because Program.code is non-unique: an owner can hold two
+            # live programs under one slug. Without this the operator gets a raw
+            # traceback for what is an ordinary, actionable refusal.
+            raise CommandError(
+                f"{exc} Delete or re-code one of them, or import as a different user."
+            ) from exc
+
+        project_count = Project.objects.filter(program=program).count()
+        self.stdout.write(
+            self.style.SUCCESS(
+                f"Imported program {program.name!r} (slug {program.code!r}) "
+                f"with {project_count} project(s)."
+            )
+        )
+
+    def _check(self, path: str, payload: Any) -> None:
+        """Report validation diagnostics for ``payload`` and exit 0/1.
+
+        Leads with what the file *claims* to be, because the first thing a dry
+        run has to answer is "did I grab the right file?" — the program slug in
+        particular, since that is what the real import would wipe and rebuild.
+        """
+        report = inspect_seed(payload)
+
+        self.stdout.write(f"Checked {path}")
+        self.stdout.write(f"  schema_version: {report.schema_version or '(missing)'}")
+        self.stdout.write(f"  program:        {report.program_name or '(unnamed)'}")
+        self.stdout.write(f"  slug:           {report.program_slug or '(missing)'}")
+        self.stdout.write(
+            f"  contents:       {report.project_count} project(s), "
+            f"{report.task_count} task(s), {report.resource_count} resource(s)"
+        )
+
+        if report.valid:
+            self.stdout.write(self.style.SUCCESS("Valid. No problems found."))
+            return
+
+        count = len(report.errors)
+        noun = "problem" if count == 1 else "problems"
+        self.stdout.write("")
+        for error in report.errors:
+            self.stdout.write(self.style.ERROR(f"  {error}"))
+        # CommandError is how a management command exits non-zero without a
+        # traceback; --check's contract is an exit code a CI job can gate on.
+        raise CommandError(f"Invalid seed document: {count} {noun} found.")
+
+    def _resolve_owner(self, username: str | None) -> Any:
+        if username:
+            owner = User.objects.filter(username=username).first()
+            if owner is None:
+                raise CommandError(f"No user with username {username!r}.")
+            return owner
+        owner = User.objects.filter(is_superuser=True).order_by("pk").first()
+        if owner is None:
+            raise CommandError(
+                "No superuser to own the program. Pass --owner <username> or create a superuser."
+            )
+        return owner

trueppm_api/apps/projects/management/commands/load_sample_project.py

@@ -0,0 +1,247 @@
+"""Load a bundled sample project (issue #375).
+
+Usage::
+
+    python manage.py load_sample_project [--sample <key>] [--owner <username>]
+                                         [--with-personas]
+
+Imports a bundled sample seed (default: the Atlas hybrid-large launch demo) and
+flags its projects as sample data. Idempotent — re-running replaces the sample.
+
+``--with-personas`` additionally gives the sample's persona accounts a usable
+login password so an evaluator can sign in *as* each persona (Alex the PM, Sarah
+the sponsor, …) rather than only viewing their work. The password is resolved the
+same way the demo seeds resolve it (#1350): ``TRUEPPM_DEMO_PASSWORD`` if set, else
+``"demo"`` under ``DEBUG``, else a random token printed once — so a fixed weak
+password can never silently reach a public instance. Without the flag the personas
+are created with unusable passwords, exactly as before.
+
+Because the load is idempotent, the flag applies to persona accounts a previous run
+already created, not only to rows this run mints (#3484). It still never overwrites
+a password a real user set, and never touches a staff/superuser account — and the
+report lists only the accounts the printed password verifiably opens, naming any it
+refused, so the command cannot claim a login state it did not produce.
+"""
+
+from __future__ import annotations
+
+import os
+import secrets
+from typing import Any
+
+from django.conf import settings
+from django.contrib.auth import get_user_model
+from django.core.management.base import BaseCommand, CommandError
+
+from trueppm_api.apps.projects.models import Project
+from trueppm_api.apps.projects.seed.samples import (
+    DEFAULT_SAMPLE,
+    SAMPLES,
+    UnknownSampleError,
+    load_sample,
+    sample_accounts,
+)
+
+User = get_user_model()
+
+DEMO_PASSWORD_ENV = "TRUEPPM_DEMO_PASSWORD"
+
+
+class Command(BaseCommand):
+    help = "Load a bundled sample project into the database."
+
+    def add_arguments(self, parser: Any) -> None:
+        parser.add_argument(
+            "--sample",
+            default=DEFAULT_SAMPLE,
+            help=f"Sample key to load. Known: {sorted(SAMPLES)}. Default: {DEFAULT_SAMPLE}.",
+        )
+        parser.add_argument(
+            "--owner",
+            help="Username to own the sample program. Defaults to the first superuser.",
+        )
+        parser.add_argument(
+            "--with-personas",
+            action="store_true",
+            help=(
+                "Give the sample's persona accounts a usable login password so you "
+                "can sign in as each one. Password: $TRUEPPM_DEMO_PASSWORD, else "
+                "'demo' under DEBUG, else a random token printed once."
+            ),
+        )
+
+    def handle(self, *args: Any, **options: Any) -> None:
+        sample_key = options["sample"]
+        owner = self._resolve_owner(options.get("owner"), sample_key)
+        with_personas = options["with_personas"]
+
+        persona_password: str | None = None
+        password_source: str | None = None
+        if with_personas:
+            persona_password, password_source = self._resolve_demo_password()
+
+        try:
+            program = load_sample(
+                sample_key, owner=owner, create_users=True, persona_password=persona_password
+            )
+        except UnknownSampleError as exc:
+            raise CommandError(str(exc)) from exc
+
+        count = Project.objects.filter(program=program).count()
+        self.stdout.write(
+            self.style.SUCCESS(
+                f"Loaded sample {program.name!r} with {count} project(s) (marked is_sample)."
+            )
+        )
+        if with_personas:
+            self._report_personas(sample_key, persona_password, password_source)
+        else:
+            self.stdout.write(
+                "  Personas created with unusable passwords (view-only). "
+                "Re-run with --with-personas to enable persona logins."
+            )
+
+    def _report_personas(self, sample_key: str, password: str | None, source: str | None) -> None:
+        """Print the persona usernames the printed password actually opens.
+
+        This is the fix's payoff (#1760): the evaluation guide told readers to
+        "Sign in as Alex", but the seeded username is ``atlas-alex`` and the
+        password was unusable. Echo both so the walkthrough actually works.
+
+        The list is built by **checking each account against the password we are
+        about to print**, not by echoing the sample's ``accounts[]`` and trusting
+        the import to have honored it. That is the #3484 defect: the importer only
+        passworded rows it *created*, so every reload printed fifteen logins that
+        did not work. The importer now covers pre-existing persona rows as well,
+        but it still (correctly) refuses a real account that already has its own
+        password and any staff/superuser row — so the report must be able to say
+        so rather than assert a state the command did not produce.
+        """
+        accounts = sample_accounts(sample_key)
+        usernames = [a.get("username", "") for a in accounts if a.get("username")]
+        by_username = {u.username: u for u in User.objects.filter(username__in=usernames)}
+
+        enabled: list[tuple[str, str]] = []
+        refused: list[tuple[str, str]] = []
+        for account in accounts:
+            username = account.get("username", "")
+            display = account.get("display_name", "")
+            user = by_username.get(username)
+            if user is not None and password is not None and user.check_password(password):
+                enabled.append((username, display))
+            else:
+                refused.append((username, self._persona_refusal_reason(user)))
+
+        # ``TRUEPPM_DEMO_PASSWORD`` (operator opt-in) and DEBUG's "demo" are safe to
+        # echo; a randomly generated production token is also printed once because
+        # there is no other way to recover it — but it is never a re-derivable value.
+        if source == "env":
+            detail = f"password set via {DEMO_PASSWORD_ENV}"
+        else:
+            detail = f"password={password!r}"
+
+        if enabled:
+            self.stdout.write(self.style.SUCCESS(f"  Persona logins enabled ({detail}):"))
+            for username, display in enabled:
+                self.stdout.write(f"    {username}  ({display})")
+        else:
+            self.stdout.write(self.style.WARNING("  No persona logins were enabled."))
+
+        if refused:
+            self.stdout.write(
+                self.style.WARNING(
+                    f"  {len(refused)} persona account(s) left untouched — "
+                    f"the password above does not open them:"
+                )
+            )
+            for username, reason in refused:
+                self.stdout.write(f"    {username}  ({reason})")
+            self.stdout.write(
+                "  To take one of these over deliberately, set its password yourself: "
+                "python manage.py changepassword <username>"
+            )
+
+    @staticmethod
+    def _persona_refusal_reason(user: Any) -> str:
+        """Why a persona account is not openable with the password just printed."""
+        if user is None:
+            return "no such account"
+        if user.is_staff or user.is_superuser:
+            return "privileged account — never re-passworded"
+        if user.has_usable_password():
+            return "pre-existing account with its own password"
+        return "password not applied"
+
+    def _resolve_demo_password(self) -> tuple[str, str]:
+        """Resolve the persona login password and its source (mirrors #1350).
+
+        A fixed weak password must never reach a public (non-DEBUG) instance.
+        Resolution order: ``TRUEPPM_DEMO_PASSWORD`` env var, then ``"demo"`` under
+        ``DEBUG``, else a random token printed once so the operator can record it.
+        """
+        env_password = os.environ.get(DEMO_PASSWORD_ENV)
+        if env_password:
+            return env_password, "env"
+        if settings.DEBUG:
+            return "demo", "debug"
+        return secrets.token_urlsafe(16), "generated"
+
+    def _resolve_owner(self, username: str | None, sample_key: str) -> Any:
+        """Resolve the program owner: explicit user, then superuser, then the sample's own.
+
+        The third fallback exists for the hosted demo (#3098). ``seed_demo_project``
+        built its own persona accounts and owned the program with one of them, so
+        the demo deployment never created a superuser — and it must not, because
+        the read-only posture (ADR-0658) rests on there being no login-capable
+        account at all. Requiring a superuser here would have made the demo stack
+        fail to boot the moment it swapped to this command.
+
+        The account is created with an **unusable** password, exactly like every
+        other persona this command creates without ``--with-personas``, so the
+        zero-login posture is preserved.
+        """
+        if username:
+            owner = User.objects.filter(username=username).first()
+            if owner is None:
+                raise CommandError(f"No user with username {username!r}.")
+            return owner
+        owner = User.objects.filter(is_superuser=True).order_by("pk").first()
+        if owner is not None:
+            return owner
+
+        try:
+            accounts = sample_accounts(sample_key)
+        except UnknownSampleError as exc:
+            raise CommandError(str(exc)) from exc
+        lead = next(
+            (a for a in accounts if a.get("role") == "OWNER"),
+            accounts[0] if accounts else None,
+        )
+        if lead is None:
+            raise CommandError(
+                "No superuser to own the sample and the sample declares no accounts. "
+                "Pass --owner <username> or create a superuser."
+            )
+        owner, created = User.objects.get_or_create(
+            username=lead["username"],
+            defaults={
+                "email": lead.get("email", ""),
+                "first_name": (lead.get("display_name") or "").split(" ")[0],
+                "last_name": " ".join((lead.get("display_name") or "").split(" ")[1:]),
+            },
+        )
+        if created:
+            # Unusable password (a sentinel hash, not a credential) — this is a
+            # seeded persona, not an interactive signup, so validators do not apply.
+            # nosemgrep: unvalidated-password
+            owner.set_password(None)
+            owner.save(update_fields=["password"])
+        # Read the state back rather than asserting the create branch's intent: on a
+        # reload the row already exists and this never touched it, so hard-coding
+        # "(unusable password)" was the same false claim as #3484's persona report.
+        state = "usable password" if owner.has_usable_password() else "unusable password"
+        self.stdout.write(
+            f"No superuser found; owning the sample with its own persona "
+            f"{lead['username']!r} ({state})."
+        )
+        return owner