trueppm-api 0.4.0b2__py3-none-any.whl

trueppm_api/apps/projects/lifecycle.py

@@ -0,0 +1,191 @@
+"""The draft exclusion list (#2962).
+
+A draft is a plan nobody has agreed to yet. It is fully writable — that is the
+difference from ``is_archived`` — but it must not appear in anything that
+*aggregates*, because a half-built plan inside a rollup makes that rollup a
+guess with a chart around it.
+
+**One module, not N filters.** The exclusion has to hold across program rollup,
+portfolio health, search and notifications, and those live in different modules
+maintained at different times. A `.exclude(lifecycle=DRAFT)` written out per
+surface is a place to forget it per surface; this module is one place to get it
+right and one place to grep for.
+
+It says *module* rather than *helper* because #3128 found the single-helper
+framing was itself part of why the list leaked. :func:`visible_projects` takes a
+``Project`` queryset, and half the surfaces that must honor the exclusion never
+build one — omni-search and the cross-project dependency picker filter ``Task``
+rows, and the Programs directory counts projects inside a ``Count(filter=...)``
+annotation on ``Program``. Faced with a helper that did not fit, those sites
+wrote nothing at all. So there are three shapes of the same predicate —
+:func:`visible_projects`, :func:`exclude_draft_projects`, :func:`not_draft_q` —
+and the rule is: **no surface writes its own draft-exclusion predicate.** If a
+new one fits none of the three, add a fourth here rather than inlining it there.
+
+Be exact about what that rule does and does not say, because the tempting
+stronger version ("``ProjectLifecycle.DRAFT`` appears in this file and nowhere
+else") is *false* and would be a trap to write down. ``commit_moment.py`` reads
+it to decide whether a project is committable, and ``amend.py`` reads its
+sibling ``ACTIVE`` — those are state *transitions*, which are none of this
+module's business. The rule covers exclusion filters only, and nothing enforces
+it mechanically today: a gate would have to tell a transition check apart from
+an exclusion filter, which is not a grep. Treat it as a convention this module
+argues for, not a guarantee something checks (#3128).
+
+**The MCP read surface is deliberately NOT on this list**, which is a correction
+to the design rather than an omission. Hiding a project from an agent's reads is
+indistinguishable from a 404 or a token-scope miss: the agent cannot tell "not
+committed yet" from "does not exist" and has no way to debug the difference.
+``lifecycle`` is returned as an ordinary field instead, so a client can filter on
+a stated fact. Filtering is something a caller can do; recovering from silence is
+not.
+
+**Two more surfaces are deliberately NOT on this list** (#3144). The #3128 audit
+found both leaking and left both, because filtering them is a decision about
+people and about their own files rather than a correctness fix about plans. Both
+decisions are KEEP, and the reasoning is recorded here so the next audit reads it
+instead of re-deriving it.
+
+*The mention fan-out* (``access.groups._program_membership_base_qs``). The
+strongest reason is structural rather than a values call. That queryset is the
+one base **all four** ``@program-*`` keys narrow, and its own docstring forbids a
+per-key filter. So a draft exclusion has no legal placement: written where it
+belongs it also drops the draft's Admin out of ``@program-pms`` and its Scheduler
+out of ``@program-schedulers`` — the people *authoring the draft*, cut out of
+program-wide coordination — and written per key it breaks the invariant the
+helper was extracted to hold. The values argument agrees: draft-ness is a
+property of the plan someone was added to, not of their standing in the program,
+and the failure mode of dropping them is silence neither they nor the sender can
+see, exactly as for the MCP surface above. Two further consequences, both
+deliberate:
+
+* ``@program-stakeholders`` has a second arm. ``ExternalStakeholder`` is
+  program-owned with **no project FK**, so no project-level narrowing can reach
+  it. Excluding the internal arm would report ``viewer_member_count: 0`` beside a
+  non-zero external count on a program whose projects are all drafts — an
+  incoherence between the arms that does not exist today.
+* A mention *written in* a draft project still fans out program-wide. That is the
+  other leak direction, and it is kept too: #3128's three notification sites were
+  unattended machine sweeps over a project population, whereas a PM typing
+  ``@program-stakeholders`` into a draft is deliberately asking for review, which
+  is what a draft is for.
+
+The cost of keeping, named so a later report traces here: draft memberships
+consume ``@program-all``'s ``ALL_GROUP_HARD_CAP`` slots, so enough drafts can trip
+``GroupTooLargeError`` on the strength of plans nobody committed to. Accepted —
+the cap is a blast-radius guard over real people, who are genuinely reached.
+
+Keeping also holds ``count_program_stakeholder_reach`` in lockstep with the
+resolver (ADR-0697) for free: the count and the fan-out cannot drift if neither
+moves. The program-settings docs say the alias reaches "members holding the Viewer
+role on any project inside the program", which stays true under KEEP; that
+sentence becomes wrong, and must gain the gap, only if this decision flips.
+
+*The cross-project asset feeds* (``projects.asset_feed``, behind
+``GET /programs/{pk}/assets/`` and ``GET /assets/``) are the member's own browse
+list, which this module exempts, at two scopes — the workspace view is literally
+the program view with the ``project__program=`` clause dropped, and both narrow to
+the caller's own ``ProjectMembership``. ``?q=`` makes them look like the
+omni-search palette this list does name, but the line under omni-search and the
+dependency picker is that a returned row is *acted on across a boundary*: the
+palette navigates into a project, the picker mints an edge that moves a real
+project's dates. Nothing downstream of an asset row changes a schedule, and the
+feed emits no count, health band or ranking that an exclusion would make truer.
+What exclusion would produce instead is a visibility discontinuity at the commit
+moment: a file you attached to your own draft disappears from the surface built to
+find it and returns when somebody else commits the plan.
+
+``GET /assets/`` is additionally a declared MCP read surface
+(``McpReadableViewMixin``), which the paragraph above exempts outright; note this
+covers only the workspace tier — ``ProgramAssetsView`` is not MCP-readable, and
+the browse-list argument is what carries it. An operator who wants a project out
+of an agent's index already has ``mcp_settings.mcp_excluded_project_ids``, a
+stated and auditable lever orthogonal to lifecycle.
+"""
+
+from __future__ import annotations
+
+from typing import Any, TypeVar
+
+from django.db.models import Model, Q, QuerySet
+
+from .models import Project, ProjectLifecycle
+
+_M = TypeVar("_M", bound=Model)
+
+
+def visible_projects(qs: QuerySet[Project]) -> QuerySet[Project]:
+    """Drop drafts from an aggregate.
+
+    Apply to any queryset feeding a rollup, a health figure, a search result or an
+    **unattended** notification fan-out over a project population. Do **not** apply
+    it to a direct read of one project by id, to the project list a member browses,
+    to the MCP read surface, or to a mention resolver, where a human named the
+    audience at write time (#3144) — a draft is not a secret, it is merely
+    uncommitted.
+    """
+    return qs.exclude(lifecycle=ProjectLifecycle.DRAFT)
+
+
+def exclude_draft_projects(qs: QuerySet[_M], path: str = "project") -> QuerySet[_M]:
+    """Drop rows whose owning project is a draft, from a *non*-Project queryset.
+
+    The same exclusion as :func:`visible_projects`, reached across a relation.
+    Two of the four surfaces the exclusion list names — omni-search and the
+    cross-project dependency picker — never build a ``Project`` queryset at all;
+    they filter ``Task`` rows by their project. Without this, those sites would
+    each have to hand-write ``exclude(project__lifecycle="draft")``, which is
+    exactly the "four places to forget it" the module docstring rejects.
+
+    ``path`` must be **single-valued** (a chain of forward FKs / one-to-ones), and
+    that is enforced below rather than documented and hoped for. On a single-valued
+    path Django appends a bare column predicate to a join it already has. On a
+    multi-valued one (``Program.projects``) the same call compiles to a correlated
+    ``NOT EXISTS`` and, far worse, silently *inverts the question*: it drops every
+    row whose related set contains **any** draft, rather than dropping draft rows.
+    That is a wrong answer, not a slow one, and nothing downstream would show it —
+    so it fails loudly here instead. For an aggregate over a multi-valued relation
+    use :func:`not_draft_q` inside the aggregate's own ``filter=``.
+
+    Args:
+        qs: Any queryset with a single-valued relation reaching ``Project``.
+        path: The ORM lookup path from ``qs``'s model to that ``Project``
+            (``"project"`` for ``Task``, ``"task__project"`` for a task's children).
+
+    Raises:
+        ValueError: If ``path`` traverses a multi-valued relation.
+    """
+    model: Any = qs.model
+    for part in path.split("__"):
+        field = model._meta.get_field(part)
+        if field.many_to_many or field.one_to_many:
+            raise ValueError(
+                f"exclude_draft_projects: path {path!r} traverses the multi-valued "
+                f"relation {part!r} on {model.__name__}. That would drop every row "
+                "whose related set contains ANY draft, not the draft rows — use "
+                "not_draft_q() inside the aggregate's filter= instead."
+            )
+        model = field.related_model
+    lookup: dict[str, Any] = {f"{path}__lifecycle": ProjectLifecycle.DRAFT}
+    return qs.exclude(**lookup)
+
+
+def not_draft_q(path: str = "") -> Q:
+    """The same exclusion as a ``Q``, for an aggregate's ``filter=`` argument.
+
+    ``Count(..., filter=...)`` takes a ``Q``, not a queryset, so the one place
+    that counts projects inside an annotation on ``Program`` cannot call either
+    helper above. It gets this instead of hand-writing the predicate, so the
+    exclusion still has one definition rather than one per surface.
+
+    Args:
+        path: The ORM lookup path to the ``Project``, or ``""`` when the
+            queryset's own model is ``Project`` (``"projects"`` from ``Program``).
+    """
+    field = f"{path}__lifecycle" if path else "lifecycle"
+    return ~Q(**{field: ProjectLifecycle.DRAFT})
+
+
+def is_draft(project: Project) -> bool:
+    """True when nobody has committed to this plan yet."""
+    return project.lifecycle == ProjectLifecycle.DRAFT

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

@@ -0,0 +1,92 @@
+"""Backfill the date-gated NOT_STARTED → IN_PROGRESS auto-transition (#336).
+
+Before #336 landed, setting `planned_start` on a NOT_STARTED task did not
+auto-transition status across most entry points (only the gutter-promote
+action did, briefly, on the frontend). This command finds rows that *should*
+have been IN_PROGRESS under the new rule and corrects them in one pass so
+the unified data model holds for existing data, not just new mutations.
+
+Targeted rows: ``status=NOT_STARTED`` AND ``planned_start <= today``.
+
+For each, the command:
+
+- Sets ``status = IN_PROGRESS``.
+- Sets ``actual_start = planned_start`` (preserving the historical date —
+  same logic as ``TaskSerializer.update`` for past-dated planned_start).
+
+Idempotent: a second run finds zero matches because the first run moved them
+out of NOT_STARTED. Safe to run repeatedly during deployment rollout.
+
+Usage::
+
+    python manage.py backfill_in_progress_status              # apply
+    python manage.py backfill_in_progress_status --dry-run    # preview only
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from django.core.management.base import BaseCommand
+from django.db import transaction
+from django.utils import timezone
+
+from trueppm_api.apps.projects.models import Task, TaskStatus
+
+logger = logging.getLogger(__name__)
+
+
+class Command(BaseCommand):
+    help = (
+        "Backfill NOT_STARTED tasks with planned_start ≤ today to IN_PROGRESS, "
+        "pinning actual_start to planned_start (#336)."
+    )
+
+    def add_arguments(self, parser: Any) -> None:
+        parser.add_argument(
+            "--dry-run",
+            action="store_true",
+            help="Print the rows that would be updated without writing.",
+        )
+
+    def handle(self, *args: Any, **options: Any) -> None:
+        today = timezone.localdate()
+        candidates = Task.objects.filter(
+            status=TaskStatus.NOT_STARTED,
+            planned_start__lte=today,
+        ).only("id", "name", "planned_start", "actual_start")
+
+        count = candidates.count()
+        if count == 0:
+            self.stdout.write(self.style.SUCCESS("No tasks to backfill."))
+            return
+
+        self.stdout.write(
+            f"Found {count} NOT_STARTED task(s) with planned_start ≤ {today.isoformat()}."
+        )
+
+        if options["dry_run"]:
+            for t in candidates[:50]:
+                self.stdout.write(f"  • {t.id} '{t.name}' planned_start={t.planned_start}")
+            if count > 50:
+                self.stdout.write(f"  … and {count - 50} more")
+            self.stdout.write(self.style.WARNING("--dry-run: no changes written."))
+            return
+
+        # Bulk update inside a transaction; preserve actual_start when it's
+        # already set (don't trample historical data) and never overwrite a
+        # status that has somehow drifted out of NOT_STARTED between the
+        # candidate query and the write.
+        updated = 0
+        with transaction.atomic():
+            for t in candidates.select_for_update():
+                if t.status != TaskStatus.NOT_STARTED:
+                    continue  # raced; another writer moved this row already
+                t.status = TaskStatus.IN_PROGRESS
+                if not t.actual_start:
+                    t.actual_start = t.planned_start
+                t.save(update_fields=["status", "actual_start"])
+                updated += 1
+
+        self.stdout.write(self.style.SUCCESS(f"Backfilled {updated} task(s)."))

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

@@ -0,0 +1,368 @@
+"""Mint (or pin) the public read-only demo share links (issues #1487, #2440).
+
+The public demo (``try.trueppm.com``) dogfoods the product's own tokenized,
+read-only share links (#283, extended to schedules by #1486) rather than a
+bespoke read-only mode: no login, no write path, near-zero abuse surface. This
+command binds :class:`~trueppm_api.apps.projects.models.ShareLink` rows to the
+seeded demo project and prints their public URLs, so both the demo compose stack
+(``docker-compose.demo.yml``) and the Helm demo-seed hook (ADR-0658) can log
+ready-to-share links on startup.
+
+**Two content kinds.** A ``SCHEDULE`` link is always minted. A ``BOARD`` link is
+minted *only when a board token is supplied* (``--token-board`` /
+``TRUEPPM_DEMO_SHARE_TOKEN_BOARD``). That asymmetry is deliberate back-compat:
+``docker-compose.demo.yml`` predates board sharing and supplies only the schedule
+token, so it keeps its existing single-link behaviour untouched, while the Helm
+path (which requires both tokens) gets both links. A board link is only worth
+having if it is stable, so there is no generated-token mode for it.
+
+Each kind needs its *own* token — ``ShareLink.token_hash`` is globally unique, so
+one raw token cannot back two links.
+
+**Two modes** (schedule only):
+
+* **Pinned (required for a hosted demo).** Set ``TRUEPPM_DEMO_SHARE_TOKEN``
+  (or pass ``--token``) to a fixed value. The command upserts a share link whose
+  hash matches that token — idempotent and, crucially, *reprintable*: the same
+  stable URL is emitted on every restart, so the demo has one deep-linkable
+  address that survives redeploys. Under Helm this is not optional: the seeder is
+  destructive and ``ShareLink.project`` is ``on_delete=CASCADE``, so an unpinned
+  link changes its URL on every upgrade.
+* **Generated (one-shot).** With no token supplied, a random token is minted
+  once and its URL printed a single time (the raw token is never stored, only its
+  hash — so it cannot be reprinted). Re-running without a pinned token reuses the
+  existing link and reminds the operator to pin a token for a stable URL.
+
+Read-only posture: this never touches the ``--with-personas`` /
+``TRUEPPM_DEMO_PASSWORD`` path (#1350). The demo is reachable *only* through the
+unauthenticated share endpoints.
+
+**Minting and serving are two different gates** (#2781). ``mint_share_link()``
+writes a row; the *read* additionally requires the ADR-0135 "Public sharing"
+policy to resolve true for the project. Because ``Workspace.public_sharing``
+defaults to ``False``, a demo built from default state minted links that every
+recipient saw as ``410 Gone`` — while this command printed a confident URL. So
+the command now turns sharing on for the project it publishes, and verifies the
+*effective* policy before printing, rather than assuming the mint implies a
+working link.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from django.core.management.base import BaseCommand, CommandError
+
+from trueppm_api.apps.projects.authentication import sha256_hex
+from trueppm_api.apps.projects.models import Project, ShareContentKind, ShareLink
+from trueppm_api.apps.projects.share_services import mint_share_link
+from trueppm_api.apps.projects.sharing_settings import (
+    public_sharing_instance_enabled,
+    resolve_effective_sharing,
+)
+
+# The project this publishes by default. It used to be imported from
+# ``seed_demo_project``, which #3098 retired when the Python seeders converged
+# into the JSON fixture format; the hosted demo now loads the bundled Atlas
+# sample (``DEFAULT_SAMPLE``) and publishes its flagship project. Overridable
+# with ``--project``.
+PROJECT_NAME = "Platform Core"
+
+# Idempotency key: a demo link is matched (and reused) by its exact label so
+# repeated runs never sprawl a fresh link per restart. The two kinds carry
+# *different* labels because the generated-mode lookup filters on label — a shared
+# label would make the two kinds collide on it.
+#
+# The SCHEDULE label is frozen at its original #1487 text on purpose: existing demo
+# deployments already hold rows carrying it, and renaming it would make the
+# generated-mode lookup miss them and mint a duplicate on the next run.
+DEMO_LABEL = "Public read-only demo (#1487)"
+DEMO_LABEL_BOARD = "Public read-only demo — board (#2440)"
+
+LABEL_BY_KIND = {
+    ShareContentKind.SCHEDULE: DEMO_LABEL,
+    ShareContentKind.BOARD: DEMO_LABEL_BOARD,
+}
+
+# URL path segment per kind — mirrors the frontend routes /share/schedule/<token>
+# and /share/board/<token>, and the API's own share/ URL patterns.
+PATH_BY_KIND = {
+    ShareContentKind.SCHEDULE: "schedule",
+    ShareContentKind.BOARD: "board",
+}
+
+TOKEN_ENV = "TRUEPPM_DEMO_SHARE_TOKEN"
+TOKEN_BOARD_ENV = "TRUEPPM_DEMO_SHARE_TOKEN_BOARD"
+BASE_URL_ENV = "TRUEPPM_DEMO_BASE_URL"
+# The printed URL is the demo's only entry point (there are no accounts), so the
+# fallback must name a host the operator running the command can actually open.
+# It is therefore the loopback origin the local `docker-compose.demo.yml` stack
+# publishes on — NOT the hosted demo's domain, which would hand a local evaluator
+# a link that resolves to somebody else's instance where their token does not
+# exist (#2801). Every hosted path sets the env var explicitly; the Helm chart
+# fails its render when `demo.baseUrl` is empty rather than falling back here.
+DEFAULT_BASE_URL = "http://localhost"
+
+
+class Command(BaseCommand):
+    """Mint or pin the public read-only demo share links (#1487, #2440)."""
+
+    help = "Create (or pin) the public read-only demo share links and print their URLs."
+
+    def add_arguments(self, parser: Any) -> None:
+        parser.add_argument(
+            "--project",
+            default=PROJECT_NAME,
+            help=(
+                f"Demo project name to share (default: {PROJECT_NAME!r}, "
+                "seeded by load_sample_project)."
+            ),
+        )
+        parser.add_argument(
+            "--token",
+            default=None,
+            help=(
+                f"Pin a fixed raw token for a stable, reprintable SCHEDULE URL. "
+                f"Falls back to the {TOKEN_ENV} env var. When omitted a random "
+                "token is minted once."
+            ),
+        )
+        parser.add_argument(
+            "--token-board",
+            default=None,
+            help=(
+                f"Pin a fixed raw token for a stable BOARD URL. Falls back to the "
+                f"{TOKEN_BOARD_ENV} env var. When omitted no board link is minted "
+                "(a board link is only useful if stable, so there is no generated "
+                "mode). Must differ from the schedule token."
+            ),
+        )
+        parser.add_argument(
+            "--base-url",
+            default=None,
+            help=(
+                f"Public base URL of the demo host (default: {BASE_URL_ENV} env "
+                f"var, else {DEFAULT_BASE_URL!r})."
+            ),
+        )
+
+    def handle(self, *args: object, **options: object) -> None:
+        project_name = str(options["project"])
+        base_url_opt = options.get("base_url")
+        base_url = (
+            str(base_url_opt) if base_url_opt else os.environ.get(BASE_URL_ENV) or DEFAULT_BASE_URL
+        ).rstrip("/")
+
+        token_opt = options.get("token")
+        schedule_token = str(token_opt) if token_opt else os.environ.get(TOKEN_ENV)
+        token_board_opt = options.get("token_board")
+        board_token = str(token_board_opt) if token_board_opt else os.environ.get(TOKEN_BOARD_ENV)
+
+        # Guard the collision early with an actionable message. Without this the
+        # second upsert would silently resolve the *first* kind's row by token_hash
+        # and report success while minting nothing.
+        if schedule_token and board_token and schedule_token == board_token:
+            raise CommandError(
+                "The schedule and board tokens are identical. ShareLink.token_hash is "
+                "globally unique, so each kind needs its own token — generate a second "
+                "one with: openssl rand -base64 32 | tr -d '=+/'"
+            )
+
+        try:
+            # Scoped to is_sample so this publishes the seeder's project and never
+            # an operator's same-named real one — Project.name is non-unique, and
+            # since #2476 the seeder no longer deletes a real project that
+            # collides with the demo name, so it can legitimately coexist here.
+            project = Project.objects.get(name=project_name, is_sample=True, is_deleted=False)
+        except Project.DoesNotExist as exc:
+            raise CommandError(
+                f"Demo project {project_name!r} not found. Run "
+                "`python manage.py load_sample_project` first."
+            ) from exc
+
+        # Turn sharing on *before* minting, so the links this run prints resolve
+        # for the recipient rather than 410-ing (#2781).
+        self._enable_public_sharing(project)
+
+        results: list[tuple[str, ShareLink, str]] = []
+
+        scheduled = self._resolve_link(project, ShareContentKind.SCHEDULE, schedule_token)
+        if scheduled is not None:
+            results.append(scheduled)
+
+        # Board is opt-in via its token — see the module docstring for why.
+        if board_token:
+            board = self._resolve_link(project, ShareContentKind.BOARD, board_token)
+            if board is not None:
+                results.append(board)
+
+        if not results:
+            return
+
+        # Re-read the posture the *recipient* will hit. Enabling sharing above is
+        # necessary but not sufficient: the operator kill switch sits above every
+        # policy, and an Enterprise ENFORCE lock outranks the project override. If
+        # either still says no, say so instead of printing a URL that 404s/410s.
+        self._warn_if_links_will_not_resolve(project)
+
+        self.stdout.write(self.style.SUCCESS("=" * 60))
+        self.stdout.write(self.style.SUCCESS("  Public read-only demo share links"))
+        self.stdout.write(self.style.SUCCESS(f"  Project:  {project.name!r}"))
+        for action, link, token in results:
+            kind_path = PATH_BY_KIND[ShareContentKind(link.content_kind)]
+            url = f"{base_url}/share/{kind_path}/{token}"
+            self.stdout.write(self.style.SUCCESS(""))
+            self.stdout.write(self.style.SUCCESS(f"  {action} {link.content_kind} link"))
+            self.stdout.write(self.style.SUCCESS(f"  Link id:  {link.id}"))
+            self.stdout.write(self.style.SUCCESS(f"  URL:      {url}"))
+        self.stdout.write(self.style.SUCCESS("=" * 60))
+
+    def _enable_public_sharing(self, project: Any) -> None:
+        """Set the demo project's own ADR-0135 ``public_sharing`` override to True.
+
+        The override is written at **project** scope, not on the workspace, and
+        that is the whole point of the choice: ``Workspace.public_sharing`` is the
+        admin-facing default for *every* project on the instance, and a management
+        command has no business flipping it. The demo project is public by
+        definition; nothing else on the instance is, and a self-hoster who seeds
+        the sample onto a real install must not find their workspace default
+        silently loosened as a side effect.
+
+        Safe by scoping: ``handle()`` resolves the project with ``is_sample=True``,
+        so the only row this can ever touch is one the seeder created.
+
+        Idempotent — a second run finds the override already true and writes
+        nothing, which keeps ``server_version`` (and the history row each save
+        writes) from advancing once per container restart.
+        """
+        if project.public_sharing:
+            return
+        project.public_sharing = True
+        project.save(update_fields=["public_sharing"])
+        self.stdout.write(
+            self.style.WARNING(
+                f"Enabled public sharing on demo project {project.name!r} "
+                "(project-scoped override; the workspace default is untouched)."
+            )
+        )
+
+    def _warn_if_links_will_not_resolve(self, project: Any) -> None:
+        """Warn when the printed URLs will not actually serve, and say why.
+
+        The mint and the read are separate gates, and this command historically
+        only exercised the first — which is how a demo shipped links that every
+        recipient saw as ``410 Gone`` while startup logs showed a confident URL
+        (#2781). Two conditions survive :meth:`_enable_public_sharing`:
+
+        * the operator kill switch (``TRUEPPM_PUBLIC_BOARD_SHARING_ENABLED=false``),
+          which outranks every policy and makes the share endpoints answer 404;
+        * an Enterprise ``ENFORCE`` sharing lock with the workspace value off,
+          under which the project override is ignored and the read answers 410.
+
+        Neither is this command's to override — an operator or a workspace admin
+        set them deliberately. Reporting them is the honest response.
+        """
+        if not public_sharing_instance_enabled():
+            self.stdout.write(
+                self.style.ERROR(
+                    "TRUEPPM_PUBLIC_BOARD_SHARING_ENABLED is false — this instance "
+                    "serves no public share links, so the URLs below will 404. Set it "
+                    "to true to run a public demo."
+                )
+            )
+            return
+        if not resolve_effective_sharing(project, "public_sharing"):
+            self.stdout.write(
+                self.style.ERROR(
+                    "Public sharing still resolves to off for this project despite the "
+                    "project-scoped override — a workspace ENFORCE policy is locking it. "
+                    "The URLs below will return 410 until a workspace admin turns "
+                    "'Public sharing' on or relaxes the override policy."
+                )
+            )
+
+    def _resolve_link(
+        self,
+        project: Any,
+        kind: ShareContentKind,
+        pinned_token: str | None,
+    ) -> tuple[str, ShareLink, str] | None:
+        """Return ``(action, link, raw_token)`` for one content kind.
+
+        Returns ``None`` when there is nothing printable — today that is only the
+        generated-mode case where a prior link exists but its raw token cannot be
+        recovered, which is a warning rather than an error.
+        """
+        if pinned_token:
+            link, created = self._upsert_pinned_link(project, kind, pinned_token)
+            return ("Created" if created else "Reused"), link, pinned_token
+
+        existing = (
+            ShareLink.objects.filter(
+                project=project,
+                content_kind=kind,
+                label=LABEL_BY_KIND[kind],
+                revoked_at__isnull=True,
+            )
+            .order_by("-created_at")
+            .first()
+        )
+        if existing is not None:
+            env_var = TOKEN_ENV if kind == ShareContentKind.SCHEDULE else TOKEN_BOARD_ENV
+            self.stdout.write(
+                self.style.WARNING(
+                    f"A generated demo {kind} share link already exists but its raw token "
+                    f"cannot be recovered. Set {env_var} to pin a stable, "
+                    "reprintable URL, or revoke it in the sharing UI and re-run."
+                )
+            )
+            return None
+
+        link, token = mint_share_link(
+            project,
+            user=None,
+            label=LABEL_BY_KIND[kind],
+            show_assignees=False,
+            content_kind=kind,
+        )
+        return "Created", link, token
+
+    def _upsert_pinned_link(
+        self,
+        project: Any,
+        kind: ShareContentKind,
+        token: str,
+    ) -> tuple[ShareLink, bool]:
+        """Return ``(link, created)`` for the pinned token, creating it if absent.
+
+        Matched by ``token_hash`` (the only stored representation of the token),
+        so a fixed token always resolves the same row and the URL is reprintable
+        across restarts — and across the destructive re-seed that a Helm upgrade
+        performs, which cascades the previous rows away entirely.
+        """
+        token_hash = sha256_hex(token)
+        link = ShareLink.objects.filter(token_hash=token_hash).first()
+        if link is not None:
+            # A token already bound to the *other* kind must not be silently
+            # reported as reused: the caller would see "Reused" and exit 0 while
+            # the link they asked for was never minted. The same-run guard in
+            # handle() only catches both-tokens-equal; this catches the cross-run
+            # case (reusing a previously-pinned schedule token as a board token).
+            if link.content_kind != kind:
+                raise CommandError(
+                    f"That token is already bound to a {link.content_kind} share link "
+                    f"(id {link.id}); it cannot also back a {kind} link because "
+                    "ShareLink.token_hash is globally unique. Use a different token."
+                )
+            return link, False
+        link = ShareLink.objects.create(
+            project=project,
+            content_kind=kind,
+            token_prefix=token[:12],
+            token_hash=token_hash,
+            label=LABEL_BY_KIND[kind],
+            show_assignees=False,
+            created_by=None,
+        )
+        return link, True