@topy-ai/maggie 0.7.1 → 0.7.2

package/README.md

@@ -66,8 +66,9 @@ Maggie in this order:
 ```bash
 python3 tools/clis/maggie.py analyze . --json --save
 python3 tools/clis/maggie.py bootstrap interview .
-python3 tools/clis/maggie_dash.py init --project . --confirm
-python3 tools/clis/maggie_dash.py migrate --project . --confirm
+maggie dash install --project . --confirm
+maggie dash init --project . --confirm
+maggie dash migrate --project . --confirm
 ```
 
 The normal daily loop is:
@@ -88,7 +89,7 @@ The CLI provides the installer plus durable workflow commands:
 maggie init | install | update | remove | list | doctor
 maggie cleanup --project . [--confirm]
 maggie bootstrap interview | phase ...
-maggie dash init | status | migrate | cms ...
+maggie dash install | init | status | migrate | cms ...
 maggie dash transition ...      # explicit content approval transition
 maggie dash variant ...         # service variant create/review/preview/publish
 maggie clone ...                 # authorized homepage capture
@@ -190,8 +191,8 @@ artifact schemas.
 Recommended upgrade sequence for the current release:
 
 ```bash
-npx @topy-ai/maggie@0.7.1 update --project . --force
-npx @topy-ai/maggie@0.7.1 cleanup --project .
+npx @topy-ai/maggie@0.7.2 update --project . --force
+npx @topy-ai/maggie@0.7.2 cleanup --project .
 ```
 
 Maintainers should pass npm credentials through the repository helper, never
@@ -201,7 +202,8 @@ as a command-line argument:
 node scripts/publish-npm.mjs --maggie-env-file ../.env
 ```
 
-The 0.7.1 workflow adds audited MaggieDash CMS operations (`cms revisions`,
+The 0.7.2 workflow adds the installable MaggieDash admin distribution and
+audited CMS operations (`cms revisions`,
 `trash`, `restore`, `schedule`, `duplicate`, `redirect`, and signed
 `preview`), import-authoritative service matching, shared translation indexes,
 sanitized seed manifests, lockfile/analytics traffic checks, semantic sitemap
@@ -215,11 +217,20 @@ For a new project, establish the local content and approval foundation before
 connecting providers or publishing:
 
 ```bash
+maggie dash install --project . --confirm
 maggie dash init --project . --confirm
 maggie dash status --project .
 maggie doctor --project .
 ```
 
+`maggie dash install` installs the first-party private MaggieDash dashboard
+source into `./_maggie/admin`, preserving local files unless `--force` is used.
+It records the resolved source revision in `.maggie/dash-install.json`. During
+bootstrap this is enabled by default; use `--dash-source /path/to/MaggieDash`
+for local development or a configured private Git URL. The host project keeps
+ownership of routes, email/password auth, database, provider credentials, and
+the `/api/maggie/*` adapter.
+
 Content remains draft-first and external writes remain explicit. Use the
 project-local memory workflow for confirmed preferences and reusable lessons;
 feedback drafts are never promoted to active memory automatically.

package/bin/maggie.js

@@ -65,7 +65,7 @@ Usage:
   maggie list
   maggie doctor [--project PATH]
   maggie bootstrap interview [project]
-  maggie dash init|status|migrate|transition|variant|cms --project PATH [options]
+  maggie dash init|install|status|migrate|transition|variant|cms --project PATH [options]
   maggie dash status --project PATH
   maggie dash migrate --project PATH --confirm
   maggie content FILE --source PROVIDER --project PATH --confirm

package/bundled-skills/maggie-dash/SKILL.md

@@ -5,8 +5,30 @@ description: Manage the MaggieDash project foundation, local content store, and
 
 # MaggieDash
 
-Use the provider-neutral MaggieDash contracts and CLI for project setup and
-content operations.
+Use the provider-neutral MaggieDash contracts and CLI for project setup,
+installation of the first-party admin workspace, and content operations.
+
+## Install the admin workspace
+
+During bootstrap, the recommended decision is to install MaggieDash into
+`./_maggie/admin`. The dashboard source lives in the private first-party
+`TOPY-AI-LTD/MaggieDash` repository during the MVP phase; Git/gh credentials
+must already be configured for the project owner.
+
+```bash
+maggie dash install --project . --confirm
+```
+
+The command is idempotent, preserves existing files unless `--force` is
+explicitly supplied, and records the resolved revision in
+`.maggie/dash-install.json`. It never accepts or stores a GitHub token as a
+CLI argument. For local development or a pinned checkout, use
+`--source /path/to/MaggieDash` or `--source URL --ref REF`.
+
+The installed dashboard owns the React workspace UI. The host project still
+owns the framework route, email/password session middleware, database, media
+storage, provider credentials, and `/api/maggie/*` adapter endpoints. Read the
+MaggieDash host adapter contract before adding a new framework adapter.
 
 ## Workflow
 

package/bundled-templates/maggiedash/README.md

@@ -11,3 +11,14 @@ marketplace repository.
 Dashboard routes should adopt `dashboard-ui-contract.json` and validate their
 actual host components with `maggie dash ui validate`. The contract provides
 the shared workspace chrome and rejects components that declare dead props.
+
+The first-party dashboard distribution is installed separately into
+`./_maggie/admin`:
+
+```bash
+maggie dash install --project . --confirm
+```
+
+It records the source revision at `.maggie/dash-install.json`; host routes,
+email/password authentication, and `/api/maggie/*` adapters remain owned by the
+website project.

package/bundled-tools/clis/maggie.py

@@ -8,6 +8,7 @@ import hashlib
 import json
 import os
 import re
+import subprocess
 import sys
 import time
 from datetime import datetime, timezone
@@ -561,6 +562,11 @@ def command_bootstrap_phase(args: argparse.Namespace) -> int:
             if analysis.get("maggiedash", {}).get("status") not in {"Detected", "Planned"}:
                 print("GATE_BLOCKED: MaggieDash project contract is unavailable.", file=sys.stderr)
                 return 2
+            bootstrap = load_state(root) or {}
+            decisions = bootstrap.get("decisions", {})
+            if decisions.get("maggiedash_admin") and not (root / STATE_DIR / "dash-install.json").exists():
+                print("GATE_BLOCKED: MaggieDash admin is enabled but not installed; run `maggie dash install --project . --confirm`.", file=sys.stderr)
+                return 2
         phase["status"] = "passed"
         phase["validation"] = args.validation
         phase["validated_at"] = utc_now()
@@ -589,7 +595,7 @@ BOOTSTRAP_QUESTIONS = [
     ("content_source", "Where should posts be stored?", ["preserve", "local-content", "database", "api-pull"]),
     ("posts_per_page", "How many posts should appear on each blog page?", ["9", "12", "6", "custom"]),
     ("grid_columns", "How many columns should the default post grid use?", ["3", "2", "4", "custom"]),
-    ("ops_dashboard", "Should the project add the private Maggie Ops dashboard after bootstrap?", ["disabled", "enabled"]),
+    ("maggiedash_admin", "Should bootstrap install the private MaggieDash admin workspace into ./_maggie/admin?", ["enabled", "disabled"]),
 ]
 
 
@@ -604,7 +610,7 @@ def question_default(key: str, analysis: dict) -> str:
     detected = analysis.get(key, {}).get("value") if isinstance(analysis.get(key), dict) else None
     if key == "posts_per_page": return "9"
     if key == "grid_columns": return "3"
-    if key == "ops_dashboard": return "disabled"
+    if key == "maggiedash_admin": return "enabled"
     return detected or {"ui_system": "preserve-or-tailwind", "icon_set": "phosphor", "font": "preserve-or-system", "database": "preserve-or-sqlite"}.get(key, "detected")
 
 
@@ -641,6 +647,8 @@ def command_bootstrap_interview(args: argparse.Namespace) -> int:
             raise RuntimeError(f"invalid answers file: {args.answers_file}") from error
         if not isinstance(loaded, dict): raise RuntimeError("answers file must contain a JSON object")
         answers.update({str(key): str(value) for key, value in loaded.items()})
+    if "maggiedash_admin" not in answers and "ops_dashboard" in answers:
+        answers["maggiedash_admin"] = answers["ops_dashboard"]
     for key, question, choices in BOOTSTRAP_QUESTIONS:
         value = answers.get(key, question_default(key, analysis))
         if not args.non_interactive and key not in answers:
@@ -665,8 +673,10 @@ def command_bootstrap_interview(args: argparse.Namespace) -> int:
         project=str(root), confirm=["foundation", "experience", "data", "publishing"],
         framework=answers["framework"], language=answers["language"], content_language=answers["content_language"],
         ui_system=answers["ui_system"], icon_set=answers["icon_set"], font=answers["font"], database=answers["database"], content_source=answers["content_source"],
-        posts_per_page=int(answers["posts_per_page"]), grid_columns=int(answers["grid_columns"]), ops_dashboard=answers["ops_dashboard"] == "enabled",
+        posts_per_page=int(answers["posts_per_page"]), grid_columns=int(answers["grid_columns"]),
+        ops_dashboard=answers["maggiedash_admin"] == "enabled", maggiedash_admin=answers["maggiedash_admin"] == "enabled",
         site_domain=answers["site_domain"], api_key_present=answers["api_key_present"], foundation_source=answers["foundation_source"], maggiedash_path=None,
+        dash_source=getattr(args, "dash_source", None),
     )
     return command_complete(complete_args)
 
@@ -685,6 +695,17 @@ def command_complete(args: argparse.Namespace) -> int:
         if foundation_analysis.get("maggiedash", {}).get("status") != "Detected":
             print("FOUNDATION_REQUIRED: use-existing-maggiedash was selected but no MaggieDash contract was detected.", file=sys.stderr)
             return 2
+    install_admin = bool(getattr(args, "maggiedash_admin", False))
+    if install_admin:
+        root.mkdir(parents=True, exist_ok=True)
+        command = [sys.executable, str(Path(__file__).with_name("maggie_dash.py")), "install", "--project", str(root), "--confirm"]
+        dash_source = getattr(args, "dash_source", None)
+        if dash_source:
+            command.extend(["--source", dash_source])
+        result = subprocess.run(command, cwd=root, check=False)
+        if result.returncode:
+            print("MAGGIEDASH_INSTALL_FAILED: bootstrap was not completed; resolve the private MaggieDash source and retry.", file=sys.stderr)
+            return result.returncode
     state = {
         "schema_version": "1.1",
         "status": "completed",
@@ -707,6 +728,7 @@ def command_complete(args: argparse.Namespace) -> int:
             "posts_per_page": args.posts_per_page,
             "grid_columns": args.grid_columns,
             "ops_dashboard": args.ops_dashboard,
+            "maggiedash_admin": install_admin,
         },
     }
     path = state_path(root)
@@ -714,7 +736,7 @@ def command_complete(args: argparse.Namespace) -> int:
     path.write_text(json.dumps(state, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
     contracts = {
         "project.json": {"schema_version": "1.0", "framework": args.framework, "language": args.language, "database": args.database, "content_source": args.content_source, "site_domain": getattr(args, "site_domain", "none"), "context_source": state["decisions"]["context_source"], "foundation_source": foundation_source},
-        "maggiedash.json": {"schema_version": "1.0", "source": foundation_source, "path": getattr(args, "maggiedash_path", None), "scaffold_command": "maggie dash init --project ." if foundation_source == "create-maggiedash" else None, "capabilities": ["content", "admin", "auth", "media", "plugins", "api", "mcp"], "status": "detected" if foundation_source == "use-existing-maggiedash" else "planned" if foundation_source == "create-maggiedash" else "not-selected"},
+        "maggiedash.json": {"schema_version": "1.0", "source": foundation_source, "path": getattr(args, "maggiedash_path", None), "scaffold_command": "maggie dash init --project ." if foundation_source == "create-maggiedash" else None, "admin_install": {"enabled": install_admin, "target": "./_maggie/admin", "state": ".maggie/dash-install.json" if install_admin else None}, "capabilities": ["content", "admin", "auth", "media", "plugins", "api", "mcp"], "status": "detected" if foundation_source == "use-existing-maggiedash" else "planned" if foundation_source == "create-maggiedash" else "not-selected"},
         "decisions.json": state["decisions"],
         "schema.json": {"post_required": ["id", "slug", "title", "content", "status", "canonicalUrl", "publishedAt", "updatedAt", "author"], "public_status": "published", "posts_per_page": args.posts_per_page, "grid_columns": args.grid_columns, "grid_default": f"{args.grid_columns}x{args.posts_per_page // args.grid_columns}"},
         "routes.json": {"public": ["/about", "/blog", "/blog/page/[page]", "/blog/[slug]", "/topics", "/topics/[slug]", "/authors/[slug]", "/sitemap.xml", "/robots.txt"], "ops": ["/ops", "/ops/posts", "/ops/posts/new", "/ops/posts/[id]/edit", "/ops/posts/[id]/preview", "/ops/topics", "/ops/sitemap", "/ops/reports", "/ops/settings/site", "/ops/settings/integrations", "/ops/operations", "/ops/wordpress", "/api/ops/summary", "/api/ops/posts", "/api/ops/topics", "/api/ops/bulk", "/api/ops/agency", "/api/ops/entities", "/api/ops/migrations/import", "/api/ops/migrations/[id]/resume", "/api/ops/wordpress/migration-plan", "/api/ops/pull/project-context", "/api/ops/pull/sync", "/api/ops/pull/sync-updates", "/api/ops/sitemap/matching-history", "/api/ops/sitemap/match", "/api/ops/sitemap/auto-detect", "/api/ops/rewrite/queue", "/api/ops/rewrite/history", "/api/ops/rewrite/policy", "/api/ops/content-tracking/report-state", "/api/ops/content-tracking/report-state/batch", "/api/ops/reports", "/api/ops/playbooks/[id]/run"]},
@@ -903,6 +925,7 @@ def parser() -> argparse.ArgumentParser:
     interview.add_argument("--answers-file", help="JSON answers for headless/CI use")
     interview.add_argument("--non-interactive", action="store_true", help="do not prompt; requires --answers-file and --confirm")
     interview.add_argument("--confirm", action="store_true", help="apply the reviewed proposal")
+    interview.add_argument("--dash-source", help="local checkout or Git URL for the MaggieDash admin source")
     interview.set_defaults(func=command_bootstrap_interview)
     phase = bootstrap_sub.add_parser("phase", help="start/pass/fail one ordered workflow phase")
     phase.add_argument("action", choices=["status", "start", "pass", "fail"])
@@ -915,11 +938,13 @@ def parser() -> argparse.ArgumentParser:
     complete.add_argument("--api-key-present", choices=["yes", "no"], default="no")
     complete.add_argument("--foundation-source", choices=["use-existing-maggiedash", "create-maggiedash", "preserve-existing-project"], default="preserve-existing-project")
     complete.add_argument("--maggiedash-path", default=None, help="path to an existing MaggieDash project contract")
+    complete.add_argument("--dash-source", help="local checkout or Git URL for the MaggieDash admin source")
     for name, default in (("framework", "detected"), ("language", "detected"), ("content-language", "confirmed"), ("ui-system", "preserve-or-tailwind"), ("icon-set", "phosphor"), ("font", "preserve-or-system"), ("database", "preserve-or-sqlite"), ("content-source", "confirmed")):
         complete.add_argument("--" + name, dest=name.replace("-", "_"), default=default)
     complete.add_argument("--posts-per-page", type=int, default=9)
     complete.add_argument("--grid-columns", type=int, default=3)
     complete.add_argument("--ops-dashboard", action=argparse.BooleanOptionalAction, default=False)
+    complete.add_argument("--maggiedash-admin", action=argparse.BooleanOptionalAction, default=False)
     complete.set_defaults(func=command_complete)
     generate = sub.add_parser("generate", help="generate stable contract or fixture files")
     generate.add_argument("target", choices=["contract", "fixture", "post", "topic", "author", "migration", "seo", "ops-page"])

package/bundled-tools/clis/maggie_dash.py

@@ -11,7 +11,12 @@ from __future__ import annotations
 
 import argparse
 import json
+import os
+import shutil
+import subprocess
 import sys
+import tempfile
+from datetime import datetime, timezone
 from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "runtime"))
@@ -38,6 +43,118 @@ def require_confirm(args: argparse.Namespace) -> None:
         raise SystemExit(2)
 
 
+DEFAULT_DASH_SOURCE = "https://github.com/TOPY-AI-LTD/MaggieDash.git"
+
+
+def utc_now() -> str:
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def git_revision(path: Path) -> str | None:
+    try:
+        result = subprocess.run(["git", "-C", str(path), "rev-parse", "HEAD"], capture_output=True, text=True, check=True)
+    except (OSError, subprocess.CalledProcessError):
+        return None
+    return result.stdout.strip() or None
+
+
+def copy_dashboard_tree(source: Path, target: Path, force: bool) -> tuple[list[str], list[str]]:
+    installed: list[str] = []
+    preserved: list[str] = []
+    target.mkdir(parents=True, exist_ok=True)
+    for path in sorted(source.rglob("*")):
+        relative = path.relative_to(source)
+        destination = target / relative
+        if path.is_dir():
+            destination.mkdir(parents=True, exist_ok=True)
+            continue
+        if destination.exists() and not force:
+            preserved.append(str(destination))
+            continue
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(path, destination)
+        installed.append(str(destination))
+    return installed, preserved
+
+
+def command_install(args: argparse.Namespace) -> int:
+    require_confirm(args)
+    root = project_root(args)
+    source_value = args.source or os.environ.get("MAGGIE_DASH_SOURCE") or DEFAULT_DASH_SOURCE
+    ref = args.ref
+    target = root / args.target
+    temporary: tempfile.TemporaryDirectory[str] | None = None
+    source = Path(source_value).expanduser().resolve() if not source_value.startswith(("https://", "http://", "git@")) else None
+    try:
+        if source is None:
+            temporary = tempfile.TemporaryDirectory(prefix="maggiedash-install-")
+            clone = ["git", "clone", "--depth", "1"]
+            if ref:
+                clone.extend(["--branch", ref])
+            clone.extend([source_value, temporary.name])
+            result = subprocess.run(clone, capture_output=True, text=True)
+            if result.returncode:
+                detail = (result.stderr or result.stdout).strip().splitlines()[-1:]
+                raise RuntimeError("MaggieDash source could not be cloned" + (f": {detail[0]}" if detail else ""))
+            source = Path(temporary.name)
+        if not source.is_dir():
+            raise RuntimeError(f"MaggieDash source directory not found: {source}")
+        manifest_path = source / "maggiedash.json"
+        if not manifest_path.exists():
+            raise RuntimeError("MaggieDash source has no maggiedash.json manifest")
+        manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+        if manifest.get("schemaVersion") != "maggiedash-distribution.v1":
+            raise RuntimeError("unsupported MaggieDash distribution schema")
+        if manifest.get("target") != "_maggie/admin" and args.target == "_maggie/admin":
+            raise RuntimeError("MaggieDash manifest target is not ./_maggie/admin")
+        installed: list[str] = []
+        preserved: list[str] = []
+        for item in manifest.get("files", []):
+            relative = Path(item)
+            if relative.is_absolute() or ".." in relative.parts:
+                raise RuntimeError(f"unsafe MaggieDash manifest path: {item}")
+            source_item = source / relative
+            if not source_item.exists():
+                raise RuntimeError(f"MaggieDash manifest file is missing: {item}")
+            if relative.parts and relative.parts[0] == "admin":
+                destination = target / Path(*relative.parts[1:])
+            else:
+                destination = target / relative
+            if source_item.is_dir():
+                current_installed, current_preserved = copy_dashboard_tree(source_item, destination, args.force)
+            else:
+                current_installed = []
+                current_preserved = []
+                if destination.exists() and not args.force:
+                    current_preserved = [str(destination)]
+                else:
+                    destination.parent.mkdir(parents=True, exist_ok=True)
+                    shutil.copy2(source_item, destination)
+                    current_installed = [str(destination)]
+            installed.extend(current_installed)
+            preserved.extend(current_preserved)
+        state = {
+            "schemaVersion": "maggiedash-install.v1",
+            "status": "installed",
+            "source": source_value,
+            "ref": ref,
+            "revision": git_revision(source),
+            "version": manifest.get("version"),
+            "target": str(target),
+            "installed": sorted(set(installed)),
+            "preserved": sorted(set(preserved)),
+            "updatedAt": utc_now(),
+        }
+        state_path = root / ".maggie" / "dash-install.json"
+        state_path.parent.mkdir(parents=True, exist_ok=True)
+        state_path.write_text(json.dumps(state, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+        emit({"status": "installed", "version": manifest.get("version"), "target": str(target), "installed": len(set(installed)), "preserved": len(set(preserved)), "state": str(state_path)})
+        return 0
+    finally:
+        if temporary is not None:
+            temporary.cleanup()
+
+
 def command_init(args: argparse.Namespace) -> int:
     require_confirm(args)
     root = project_root(args)
@@ -171,6 +288,14 @@ def parser() -> argparse.ArgumentParser:
     init.add_argument("--locale", default="en-GB")
     init.add_argument("--confirm", action="store_true")
     init.set_defaults(func=command_init)
+    install = sub.add_parser("install", help="install the MaggieDash admin workspace")
+    install.add_argument("--project", default=".")
+    install.add_argument("--source", help="local checkout or Git URL; defaults to MaggieDash repository")
+    install.add_argument("--ref", default="main", help="Git ref when installing from a remote source")
+    install.add_argument("--target", default="_maggie/admin", help="installation target relative to the project")
+    install.add_argument("--force", action="store_true", help="replace existing dashboard files")
+    install.add_argument("--confirm", action="store_true")
+    install.set_defaults(func=command_install)
     status = sub.add_parser("status", help="inspect project and documents")
     status.add_argument("--project", default=".")
     status.add_argument("--project-id", default="local-project")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topy-ai/maggie",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "description": "Install and manage Maggie Skills for AI coding agents",
   "license": "MIT",
   "type": "module",