enow-cli 0.1.0__py3-none-any.whl

enow_cli/__init__.py

@@ -0,0 +1,2 @@
+"""EmpowerNow extension deploy CLI."""
+__version__ = "0.1.0"

enow_cli/deploy.py

@@ -0,0 +1,250 @@
+"""
+Extension deploy engine.
+
+Copies extension artifacts into ServiceConfigs, handles PDP config
+merges, policy overlays, and experience plugin builds — all driven
+by extension.yaml.
+"""
+from __future__ import annotations
+
+import shutil
+import subprocess
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .manifest import ExtensionManifest, FileMapping, YamlMerge, PluginBuild, file_hash
+
+
+@dataclass
+class DeployAction:
+    """A single deploy action with its result."""
+    kind: str  # COPY, SKIP, MERGE, MKDIR, BUILD, HASH, ERROR
+    path: str
+    detail: str = ""
+
+
+@dataclass
+class DeployResult:
+    """Outcome of a deploy run."""
+    actions: list[DeployAction] = field(default_factory=list)
+    copied: int = 0
+    unchanged: int = 0
+    merged: int = 0
+    errors: int = 0
+
+    @property
+    def success(self) -> bool:
+        return self.errors == 0
+
+
+def deploy_extension(
+    manifest: ExtensionManifest,
+    serviceconfigs_root: Path,
+    dry_run: bool = False,
+) -> DeployResult:
+    """
+    Deploy an extension package into ServiceConfigs.
+
+    Steps:
+    1. Sync extension files into extensions/<id>/
+    2. Copy PDP policy files into pdp/config/policies/
+    3. Merge YAML fragments into shared PDP configs
+    4. Build experience plugins and copy bundles + update integrity
+    """
+    result = DeployResult()
+    ext_target = serviceconfigs_root / "extensions" / manifest.id
+    pdp_config = serviceconfigs_root / "pdp" / "config"
+
+    _sync_files(manifest.get_file_mappings(), ext_target, dry_run, result)
+    _copy_policies(manifest.get_policy_copies(), pdp_config, dry_run, result)
+    _merge_yamls(manifest.get_yaml_merges(), pdp_config, dry_run, result)
+    _build_plugins(manifest.get_plugin_builds(), serviceconfigs_root, dry_run, result)
+
+    return result
+
+
+def diff_extension(
+    manifest: ExtensionManifest,
+    serviceconfigs_root: Path,
+) -> list[DeployAction]:
+    """Show what would change without modifying anything."""
+    actions: list[DeployAction] = []
+    ext_target = serviceconfigs_root / "extensions" / manifest.id
+
+    for fm in manifest.get_file_mappings():
+        dst = ext_target / fm.dst_relative
+        if not fm.exists:
+            actions.append(DeployAction("MISSING", fm.dst_relative, f"Source: {fm.src}"))
+            continue
+        if not dst.is_file():
+            actions.append(DeployAction("NEW", fm.dst_relative))
+        elif file_hash(fm.src) != file_hash(dst):
+            actions.append(DeployAction("CHANGED", fm.dst_relative))
+
+    pdp_config = serviceconfigs_root / "pdp" / "config"
+    for merge in manifest.get_yaml_merges():
+        target = pdp_config / merge.target_relative
+        if not target.is_file():
+            actions.append(DeployAction("NEW", f"pdp/config/{merge.target_relative}"))
+        else:
+            content = target.read_text(encoding="utf-8")
+            if merge.marker not in content:
+                actions.append(DeployAction("MERGE", f"pdp/config/{merge.target_relative}", f"marker: {merge.marker}"))
+
+    return actions
+
+
+def _sync_files(
+    mappings: list[FileMapping],
+    target_root: Path,
+    dry_run: bool,
+    result: DeployResult,
+) -> None:
+    for fm in mappings:
+        dst = target_root / fm.dst_relative
+        if not fm.exists:
+            result.actions.append(DeployAction("MISSING", fm.dst_relative, f"{fm.src}"))
+            result.errors += 1
+            continue
+
+        if dst.is_file() and file_hash(fm.src) == file_hash(dst):
+            result.actions.append(DeployAction("SKIP", fm.dst_relative))
+            result.unchanged += 1
+            continue
+
+        if not dry_run:
+            dst.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(fm.src, dst)
+
+        result.actions.append(DeployAction("COPY", fm.dst_relative))
+        result.copied += 1
+
+
+def _copy_policies(
+    policies: list[FileMapping],
+    pdp_config_root: Path,
+    dry_run: bool,
+    result: DeployResult,
+) -> None:
+    for fm in policies:
+        dst = pdp_config_root / fm.dst_relative
+        if not fm.exists:
+            result.actions.append(DeployAction("MISSING", fm.dst_relative, f"{fm.src}"))
+            result.errors += 1
+            continue
+
+        if dst.is_file() and file_hash(fm.src) == file_hash(dst):
+            result.actions.append(DeployAction("SKIP", f"pdp/{fm.dst_relative}"))
+            result.unchanged += 1
+            continue
+
+        if not dry_run:
+            dst.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(fm.src, dst)
+
+        result.actions.append(DeployAction("COPY", f"pdp/{fm.dst_relative}"))
+        result.copied += 1
+
+
+def _merge_yamls(
+    merges: list[YamlMerge],
+    pdp_config_root: Path,
+    dry_run: bool,
+    result: DeployResult,
+) -> None:
+    for merge in merges:
+        if not merge.src.is_file():
+            result.actions.append(DeployAction("MISSING", merge.target_relative, f"{merge.src}"))
+            result.errors += 1
+            continue
+
+        target = pdp_config_root / merge.target_relative
+        if not target.is_file():
+            if not dry_run:
+                target.parent.mkdir(parents=True, exist_ok=True)
+                shutil.copy2(merge.src, target)
+            result.actions.append(DeployAction("COPY", f"pdp/config/{merge.target_relative}", "new file"))
+            result.copied += 1
+            continue
+
+        content = target.read_text(encoding="utf-8")
+        if merge.marker and merge.marker in content:
+            result.actions.append(DeployAction("SKIP", f"pdp/config/{merge.target_relative}", f"marker '{merge.marker}' present"))
+            result.unchanged += 1
+            continue
+
+        if not dry_run:
+            fragment = merge.src.read_text(encoding="utf-8")
+            separator = "\n" if content.endswith("\n") else "\n\n"
+            with open(target, "a", encoding="utf-8") as f:
+                f.write(separator + fragment)
+
+        result.actions.append(DeployAction("MERGE", f"pdp/config/{merge.target_relative}", f"appended '{merge.marker}'"))
+        result.merged += 1
+
+
+def _build_plugins(
+    plugins: list[PluginBuild],
+    serviceconfigs_root: Path,
+    dry_run: bool,
+    result: DeployResult,
+) -> None:
+    for plugin in plugins:
+        pkg_json = plugin.source_dir / "package.json"
+        if not pkg_json.is_file():
+            result.actions.append(DeployAction("SKIP", f"plugin:{plugin.plugin_id}", "no package.json"))
+            return
+
+        if dry_run:
+            result.actions.append(DeployAction("BUILD", f"plugin:{plugin.plugin_id}", "would build"))
+            result.actions.append(DeployAction("COPY", f"BFF/plugins/{plugin.plugin_id}/{plugin.version}/index.esm.js"))
+            result.actions.append(DeployAction("HASH", f"BFF/config/plugins/manifests/{plugin.plugin_id}.yaml"))
+            return
+
+        node_modules = plugin.source_dir / "node_modules"
+        if not node_modules.is_dir():
+            proc = subprocess.run(
+                ["npm", "install", "--silent"],
+                cwd=plugin.source_dir,
+                capture_output=True, text=True,
+            )
+            if proc.returncode != 0:
+                result.actions.append(DeployAction("ERROR", f"plugin:{plugin.plugin_id}", f"npm install failed: {proc.stderr[:200]}"))
+                result.errors += 1
+                continue
+
+        proc = subprocess.run(
+            plugin.build_command.split(),
+            cwd=plugin.source_dir,
+            capture_output=True, text=True,
+        )
+        if proc.returncode != 0:
+            result.actions.append(DeployAction("ERROR", f"plugin:{plugin.plugin_id}", f"build failed: {proc.stderr[:200]}"))
+            result.errors += 1
+            continue
+
+        result.actions.append(DeployAction("BUILD", f"plugin:{plugin.plugin_id}", "success"))
+
+        bundle_src = plugin.bundle_path
+        if not bundle_src.is_file():
+            result.actions.append(DeployAction("ERROR", f"plugin:{plugin.plugin_id}", f"bundle not found: {bundle_src}"))
+            result.errors += 1
+            continue
+
+        bundle_dst = serviceconfigs_root / "BFF" / "plugins" / plugin.plugin_id / plugin.version / "index.esm.js"
+        bundle_dst.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(bundle_src, bundle_dst)
+        result.actions.append(DeployAction("COPY", str(bundle_dst.relative_to(serviceconfigs_root))))
+        result.copied += 1
+
+        integrity = f"sha256:{file_hash(bundle_dst)}"
+        manifest_path = serviceconfigs_root / "BFF" / "config" / "plugins" / "manifests" / f"{plugin.plugin_id}.yaml"
+        if manifest_path.is_file():
+            content = manifest_path.read_text(encoding="utf-8")
+            import re
+            updated = re.sub(r"integrity:\s*sha256:[a-f0-9]+", f"integrity: {integrity}", content)
+            if updated != content:
+                manifest_path.write_text(updated, encoding="utf-8")
+                result.actions.append(DeployAction("HASH", str(manifest_path.relative_to(serviceconfigs_root)), integrity))
+        else:
+            result.actions.append(DeployAction("WARN", f"manifests/{plugin.plugin_id}.yaml", "not found — update integrity manually"))

enow_cli/main.py

@@ -0,0 +1,215 @@
+"""
+enow CLI — EmpowerNow extension management tool.
+
+Usage:
+    enow extension validate [PATH]
+    enow extension deploy --target <serviceconfigs> [--dry-run]
+    enow extension diff --target <serviceconfigs>
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import click
+
+from .manifest import ExtensionManifest, ManifestError
+from .deploy import deploy_extension, diff_extension
+from .scaffold import scaffold_extension, ALL_SURFACES, DEFAULT_SURFACES
+
+
+def _find_manifest(path: str | None) -> Path:
+    """Resolve extension.yaml from a path or current directory."""
+    if path:
+        p = Path(path)
+        if p.is_file() and p.name == "extension.yaml":
+            return p
+        if p.is_dir():
+            candidate = p / "extension.yaml"
+            if candidate.is_file():
+                return candidate
+            raise click.ClickException(f"No extension.yaml found in {p}")
+        raise click.ClickException(f"Path not found: {p}")
+
+    cwd = Path.cwd()
+    candidate = cwd / "extension.yaml"
+    if candidate.is_file():
+        return candidate
+
+    for parent in cwd.parents:
+        candidate = parent / "extension.yaml"
+        if candidate.is_file():
+            return candidate
+        if (parent / ".git").exists():
+            break
+
+    raise click.ClickException(
+        "No extension.yaml found. Run from an extension repo or pass --path."
+    )
+
+
+@click.group()
+@click.version_option()
+def cli():
+    """EmpowerNow extension management CLI."""
+    pass
+
+
+@cli.group()
+def extension():
+    """Manage extension packages."""
+    pass
+
+
+@extension.command()
+@click.argument("path", required=False)
+def validate(path: str | None):
+    """Validate an extension.yaml manifest and check all referenced files exist."""
+    manifest_path = _find_manifest(path)
+    click.echo(f"Validating: {manifest_path}")
+
+    try:
+        manifest = ExtensionManifest.load(manifest_path)
+    except ManifestError as e:
+        click.secho(f"FAIL  Manifest error: {e}", fg="red")
+        sys.exit(1)
+
+    click.echo(f"  id:        {manifest.id}")
+    click.echo(f"  version:   {manifest.version}")
+    click.echo(f"  status:    {manifest.status}")
+    click.echo(f"  enabled:   {manifest.enabled}")
+    click.echo(f"  namespace: {manifest.namespace}")
+    click.echo()
+
+    errors = manifest.validate_files()
+    mappings = manifest.get_file_mappings()
+    merges = manifest.get_yaml_merges()
+    plugins = manifest.get_plugin_builds()
+    policies = manifest.get_policy_copies()
+
+    click.echo(f"Files:    {len(mappings)} mapped")
+    click.echo(f"Merges:   {len(merges)} YAML merge(s)")
+    click.echo(f"Policies: {len(policies)} policy file(s)")
+    click.echo(f"Plugins:  {len(plugins)} experience plugin(s)")
+    click.echo()
+
+    if errors:
+        click.secho(f"FAIL  {len(errors)} error(s):", fg="red")
+        for err in errors:
+            click.secho(f"  {err}", fg="red")
+        sys.exit(1)
+    else:
+        click.secho("OK  All referenced files exist.", fg="green")
+
+
+@extension.command()
+@click.option("--target", "-t", required=True, type=click.Path(exists=True),
+              help="Path to ServiceConfigs repo root")
+@click.option("--dry-run", is_flag=True, help="Show what would change without modifying files")
+@click.option("--path", "-p", default=None, help="Path to extension repo or extension.yaml")
+def deploy(target: str, dry_run: bool, path: str | None):
+    """Deploy extension package into ServiceConfigs."""
+    manifest_path = _find_manifest(path)
+    manifest = ExtensionManifest.load(manifest_path)
+
+    click.echo(f"Deploying: {manifest.id} v{manifest.version}")
+    click.echo(f"  Source: {manifest.root}")
+    click.echo(f"  Target: {target}")
+    if dry_run:
+        click.secho("  [DRY RUN]", fg="yellow")
+    click.echo()
+
+    result = deploy_extension(manifest, Path(target), dry_run=dry_run)
+
+    for action in result.actions:
+        color = {
+            "COPY": "green", "MERGE": "green", "BUILD": "cyan",
+            "HASH": "cyan", "SKIP": None, "MISSING": "red",
+            "ERROR": "red", "WARN": "yellow", "MKDIR": None,
+        }.get(action.kind, None)
+        detail = f" ({action.detail})" if action.detail else ""
+        click.secho(f"  {action.kind:<7} {action.path}{detail}", fg=color)
+
+    click.echo()
+    click.echo(
+        f"Done: {result.copied} copied, {result.merged} merged, "
+        f"{result.unchanged} unchanged, {result.errors} errors"
+    )
+
+    if not result.success:
+        sys.exit(1)
+
+
+@extension.command()
+@click.option("--target", "-t", required=True, type=click.Path(exists=True),
+              help="Path to ServiceConfigs repo root")
+@click.option("--path", "-p", default=None, help="Path to extension repo or extension.yaml")
+def diff(target: str, path: str | None):
+    """Show what would change in ServiceConfigs (no modifications)."""
+    manifest_path = _find_manifest(path)
+    manifest = ExtensionManifest.load(manifest_path)
+
+    click.echo(f"Diff: {manifest.id} v{manifest.version} -> {target}")
+    click.echo()
+
+    actions = diff_extension(manifest, Path(target))
+
+    if not actions:
+        click.secho("No changes needed — target is up to date.", fg="green")
+        return
+
+    for action in actions:
+        color = {"NEW": "green", "CHANGED": "yellow", "MERGE": "cyan", "MISSING": "red"}.get(action.kind, None)
+        detail = f" ({action.detail})" if action.detail else ""
+        click.secho(f"  {action.kind:<8} {action.path}{detail}", fg=color)
+
+    click.echo()
+    click.echo(f"{len(actions)} change(s) pending.")
+
+
+@extension.command()
+@click.option("--name", "-n", required=True, help="Extension id (e.g. acme-corp)")
+@click.option("--namespace", "-ns", required=True, help="Short namespace prefix (e.g. acme)")
+@click.option(
+    "--surface", "-s", multiple=True,
+    type=click.Choice(ALL_SURFACES, case_sensitive=False),
+    help="Surfaces to include (repeatable). Defaults: config_pack, policy_pack, membership_projection, seed_data",
+)
+@click.option("--customer", "-c", default="", help="Customer name for the owner block")
+@click.option("--team", default="platform-engineering", help="Team name for the owner block")
+@click.option("--output", "-o", default=".", type=click.Path(), help="Output parent directory")
+def scaffold(name: str, namespace: str, surface: tuple[str, ...], customer: str, team: str, output: str):
+    """Generate a new extension package from a template."""
+    surfaces = list(surface) if surface else None
+    output_path = Path(output)
+
+    click.echo(f"Scaffolding extension: {name}")
+    click.echo(f"  Namespace: {namespace}")
+    click.echo(f"  Surfaces:  {', '.join(surfaces or DEFAULT_SURFACES)}")
+    click.echo(f"  Output:    {output_path / name}")
+    click.echo()
+
+    result = scaffold_extension(
+        output_dir=output_path,
+        name=name,
+        namespace=namespace,
+        surfaces=surfaces,
+        customer=customer,
+        team=team,
+    )
+
+    click.secho(f"Created {len(result.files_created)} files:", fg="green")
+    for f in result.files_created:
+        rel = Path(f).relative_to(result.root) if Path(f).is_relative_to(result.root) else f
+        click.echo(f"  {rel}")
+
+    click.echo()
+    click.secho("Next steps:", fg="cyan")
+    click.echo(f"  1. cd {result.root}")
+    click.echo(f"  2. Edit extension.yaml and fill in capabilities")
+    click.echo(f"  3. enow extension validate")
+    click.echo(f"  4. enow extension deploy --target /path/to/ServiceConfigs")
+
+
+if __name__ == "__main__":
+    cli()

enow_cli/manifest.py

@@ -0,0 +1,278 @@
+"""
+Extension manifest loader for the deploy CLI.
+
+Parses extension.yaml, validates structure and file references,
+and provides the deploy plan (which files go where).
+"""
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+REQUIRED_FIELDS = {"id", "version", "enabled"}
+VALID_STATUSES = {"prototype", "preview", "ga", "production", "demo", "deprecated"}
+VALID_SURFACES = {
+    "pdp_resource_handler", "pdp_resource_pip", "config_pack", "policy_pack",
+    "sidecar_adapter", "membership_projection", "experience_plugin", "seed_data",
+}
+
+
+class ManifestError(Exception):
+    pass
+
+
+@dataclass
+class FileMapping:
+    """A single file to copy from extension source to ServiceConfigs target."""
+    src: Path
+    dst_relative: str
+    category: str
+
+    @property
+    def exists(self) -> bool:
+        return self.src.is_file()
+
+
+@dataclass
+class YamlMerge:
+    """A YAML fragment to append-if-missing into a shared PDP config file."""
+    src: Path
+    target_relative: str
+    marker: str
+
+
+@dataclass
+class PluginBuild:
+    """An experience plugin that needs npm build + bundle copy + integrity update."""
+    plugin_id: str
+    source_dir: Path
+    build_command: str
+    bundle_path: Path
+    version: str = "1.0.0"
+
+
+@dataclass
+class ExtensionManifest:
+    """Parsed extension.yaml with deploy plan generation."""
+    id: str
+    namespace: str
+    version: str
+    status: str
+    enabled: bool
+    root: Path
+    raw: dict = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def load(cls, path: Path) -> ExtensionManifest:
+        if not path.is_file():
+            raise ManifestError(f"Manifest not found: {path}")
+
+        with open(path, "r", encoding="utf-8") as f:
+            raw = yaml.safe_load(f) or {}
+
+        missing = REQUIRED_FIELDS - set(raw.keys())
+        if missing:
+            raise ManifestError(f"Missing required fields: {missing}")
+
+        ext_id = raw["id"]
+        if not isinstance(ext_id, str) or not ext_id.strip():
+            raise ManifestError("'id' must be a non-empty string")
+
+        status = raw.get("status", "prototype")
+        if status not in VALID_STATUSES:
+            raise ManifestError(f"Invalid status '{status}'. Valid: {VALID_STATUSES}")
+
+        return cls(
+            id=ext_id,
+            namespace=raw.get("namespace", ext_id),
+            version=raw["version"],
+            status=status,
+            enabled=bool(raw.get("enabled", True)),
+            root=path.parent,
+            raw=raw,
+        )
+
+    def validate_files(self) -> list[str]:
+        """Check that all referenced files actually exist. Returns list of errors."""
+        errors: list[str] = []
+        for fm in self.get_file_mappings():
+            if not fm.exists:
+                errors.append(f"[{fm.category}] Missing: {fm.src}")
+        for merge in self.get_yaml_merges():
+            if not merge.src.is_file():
+                errors.append(f"[yaml_merge] Missing: {merge.src}")
+        for plugin in self.get_plugin_builds():
+            pkg_json = plugin.source_dir / "package.json"
+            if not pkg_json.is_file():
+                errors.append(f"[plugin:{plugin.plugin_id}] Missing: {pkg_json}")
+        return errors
+
+    def get_file_mappings(self) -> list[FileMapping]:
+        """Build the full list of files to sync from source to extensions/<id>/."""
+        mappings: list[FileMapping] = []
+        root = self.root
+
+        mappings.append(FileMapping(
+            src=root / "extension.yaml",
+            dst_relative="extension.yaml",
+            category="manifest",
+        ))
+
+        for cap in self.raw.get("capabilities", {}).get("pdp_resource_handlers", []):
+            cls_path = cap.get("class", "")
+            if cls_path:
+                py_path = cls_path.replace(".", "/") + ".py"
+                parts = py_path.rsplit("/", 1)
+                if len(parts) == 2:
+                    py_path = "/".join(parts[:-1]) + ".py"
+                else:
+                    py_path = parts[0]
+                py_path = cls_path.rsplit(".", 1)[0].replace(".", "/") + ".py"
+                mappings.append(FileMapping(
+                    src=root / py_path,
+                    dst_relative=py_path,
+                    category="pdp_handler",
+                ))
+
+        for cap in self.raw.get("capabilities", {}).get("membership_projections", []):
+            module = cap.get("module", "")
+            if module:
+                py_path = module.replace(".", "/") + ".py"
+                mappings.append(FileMapping(
+                    src=root / py_path,
+                    dst_relative=py_path,
+                    category="projection",
+                ))
+        init_path = root / "membership" / "projections" / "__init__.py"
+        if init_path.is_file():
+            mappings.append(FileMapping(
+                src=init_path,
+                dst_relative="membership/projections/__init__.py",
+                category="projection",
+            ))
+
+        for seed in self.raw.get("capabilities", {}).get("seed_data", []):
+            seed_path = seed if isinstance(seed, str) else seed.get("ref", seed)
+            mappings.append(FileMapping(
+                src=root / seed_path,
+                dst_relative=seed_path,
+                category="seed",
+            ))
+
+        for sidecar in self.raw.get("capabilities", {}).get("sidecars", []):
+            frag = sidecar.get("compose_fragment", "") if isinstance(sidecar, dict) else ""
+            if frag:
+                mappings.append(FileMapping(
+                    src=root / frag,
+                    dst_relative=frag,
+                    category="sidecar",
+                ))
+                sidecar_dir = root / Path(frag).parent
+                if sidecar_dir.is_dir():
+                    for f in sidecar_dir.rglob("*"):
+                        if f.is_file() and f.name != Path(frag).name:
+                            rel = f.relative_to(root)
+                            mappings.append(FileMapping(
+                                src=f,
+                                dst_relative=str(rel).replace("\\", "/"),
+                                category="sidecar",
+                            ))
+
+        return mappings
+
+    def get_yaml_merges(self) -> list[YamlMerge]:
+        """Get YAML merge operations for shared PDP config files."""
+        merges: list[YamlMerge] = []
+        for pack in self.raw.get("capabilities", {}).get("config_packs", []):
+            ref = pack.get("ref", "") if isinstance(pack, dict) else pack
+            pack_type = pack.get("type", "") if isinstance(pack, dict) else ""
+            if not ref:
+                continue
+
+            src = self.root / ref
+            if pack_type == "policies":
+                continue
+
+            target_name = Path(ref).name
+            marker = _extract_yaml_root_key(src) or f"{self.id}:"
+
+            merges.append(YamlMerge(
+                src=src,
+                target_relative=target_name,
+                marker=marker,
+            ))
+        return merges
+
+    def get_plugin_builds(self) -> list[PluginBuild]:
+        """Get experience plugins that need building."""
+        builds: list[PluginBuild] = []
+        for plugin in self.raw.get("capabilities", {}).get("experience_plugins", []):
+            if not isinstance(plugin, dict):
+                continue
+            source = plugin.get("source", "")
+            builds.append(PluginBuild(
+                plugin_id=plugin.get("id", ""),
+                source_dir=self.root / source,
+                build_command=plugin.get("build_command", "npm run build"),
+                bundle_path=self.root / plugin.get("bundle", ""),
+            ))
+        return builds
+
+    def get_policy_copies(self) -> list[FileMapping]:
+        """Get policy files that go directly to PDP config/policies/."""
+        copies: list[FileMapping] = []
+        for pack in self.raw.get("capabilities", {}).get("config_packs", []):
+            if not isinstance(pack, dict):
+                continue
+            if pack.get("type") != "policies":
+                continue
+            ref = pack.get("ref", "")
+            if not ref:
+                continue
+
+            src_path = self.root / ref
+            if src_path.is_dir():
+                for f in src_path.rglob("*"):
+                    if f.is_file():
+                        rel = f.relative_to(self.root / "pdp" / "config")
+                        copies.append(FileMapping(
+                            src=f,
+                            dst_relative=str(rel).replace("\\", "/"),
+                            category="policy",
+                        ))
+            elif src_path.is_file():
+                rel = src_path.relative_to(self.root / "pdp" / "config")
+                copies.append(FileMapping(
+                    src=src_path,
+                    dst_relative=str(rel).replace("\\", "/"),
+                    category="policy",
+                ))
+        return copies
+
+
+def _extract_yaml_root_key(path: Path) -> str:
+    """Extract the first top-level key from a YAML file to use as an idempotency marker."""
+    if not path.is_file():
+        return ""
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            data = yaml.safe_load(f)
+        if isinstance(data, dict) and data:
+            first_key = next(iter(data))
+            return f"{first_key}:"
+    except Exception:
+        pass
+    return ""
+
+
+def file_hash(path: Path) -> str:
+    """SHA-256 hex digest of a file."""
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        for chunk in iter(lambda: f.read(8192), b""):
+            h.update(chunk)
+    return h.hexdigest()

enow_cli/scaffold.py

@@ -0,0 +1,462 @@
+"""
+Extension scaffold generator.
+
+Creates a new extension directory structure with all required files
+based on the selected surfaces. The generated extension is immediately
+deployable via ``enow extension deploy``.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Sequence
+
+import yaml
+
+
+ALL_SURFACES = [
+    "config_pack",
+    "policy_pack",
+    "membership_projection",
+    "pdp_resource_pip",
+    "pdp_resource_handler",
+    "seed_data",
+    "experience_plugin",
+    "sidecar_adapter",
+]
+
+DEFAULT_SURFACES = [
+    "config_pack",
+    "policy_pack",
+    "membership_projection",
+    "seed_data",
+]
+
+
+@dataclass
+class ScaffoldResult:
+    """Tracks files created during scaffold."""
+    root: Path
+    files_created: list[str] = field(default_factory=list)
+    directories_created: list[str] = field(default_factory=list)
+
+
+def scaffold_extension(
+    output_dir: Path,
+    name: str,
+    namespace: str,
+    surfaces: Sequence[str] | None = None,
+    customer: str = "",
+    team: str = "platform-engineering",
+) -> ScaffoldResult:
+    """Generate a new extension package directory.
+
+    Parameters
+    ----------
+    output_dir:
+        Parent directory where ``<name>/`` will be created.
+    name:
+        Extension id (e.g. ``acme-corp``).  Used as directory name and
+        extension id in the manifest.
+    namespace:
+        Short namespace prefix for the extension (e.g. ``acme``).
+    surfaces:
+        Which extension surfaces to include.  Defaults to the four most
+        common: config_pack, policy_pack, membership_projection, seed_data.
+    customer:
+        Customer name for the ``owner`` block.
+    team:
+        Team name for the ``owner`` block.
+    """
+    surfaces = list(surfaces or DEFAULT_SURFACES)
+    root = output_dir / name
+    result = ScaffoldResult(root=root)
+
+    root.mkdir(parents=True, exist_ok=True)
+    result.directories_created.append(str(root))
+
+    _write_extension_yaml(root, name, namespace, surfaces, customer, team, result)
+
+    if "config_pack" in surfaces or "policy_pack" in surfaces:
+        _scaffold_pdp_config(root, name, namespace, result)
+
+    if "membership_projection" in surfaces:
+        _scaffold_projections(root, namespace, result)
+
+    if "seed_data" in surfaces:
+        _scaffold_seed_data(root, namespace, result)
+
+    if "pdp_resource_pip" in surfaces:
+        _scaffold_pip(root, namespace, result)
+
+    if "pdp_resource_handler" in surfaces:
+        _scaffold_handler(root, namespace, result)
+
+    if "experience_plugin" in surfaces:
+        _scaffold_experience_plugin(root, name, namespace, result)
+
+    if "sidecar_adapter" in surfaces:
+        _scaffold_sidecar(root, name, result)
+
+    _scaffold_tests(root, name, result)
+
+    return result
+
+
+def _mk(parent: Path, *parts: str, result: ScaffoldResult) -> Path:
+    """Create a directory and record it."""
+    d = parent.joinpath(*parts)
+    d.mkdir(parents=True, exist_ok=True)
+    result.directories_created.append(str(d))
+    return d
+
+
+def _write(path: Path, content: str, result: ScaffoldResult) -> None:
+    """Write a file and record it."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+    result.files_created.append(str(path))
+
+
+def _write_extension_yaml(
+    root: Path,
+    name: str,
+    namespace: str,
+    surfaces: list[str],
+    customer: str,
+    team: str,
+    result: ScaffoldResult,
+) -> None:
+    manifest: dict = {
+        "id": name,
+        "namespace": namespace,
+        "version": "0.1.0",
+        "status": "prototype",
+        "enabled": True,
+        "owner": {
+            "team": team,
+            "customer": customer or name,
+        },
+        "host_compatibility": {
+            "pdp": ">=1.0.0",
+            "membership": ">=1.0.0",
+        },
+        "surfaces": surfaces,
+        "capabilities": {},
+        "dependencies": {
+            "services": ["membership", "pdp"],
+        },
+    }
+
+    caps = manifest["capabilities"]
+
+    if "membership_projection" in surfaces:
+        cls_name = _class_name(namespace, "UserProjection")
+        caps["membership_projections"] = [
+            {
+                "id": f"{namespace}_user_view",
+                "module": f"membership.projections.{namespace}_user_projection",
+                "class": cls_name,
+            }
+        ]
+
+    if "pdp_resource_pip" in surfaces:
+        caps["pdp_resource_pips"] = [
+            {
+                "resource_type": f"{namespace}.entitlement",
+                "module": f"pdp.pips.{namespace}_pip",
+                "class": _class_name(namespace, "PIP"),
+            }
+        ]
+
+    if "pdp_resource_handler" in surfaces:
+        caps["pdp_resource_handlers"] = [
+            {
+                "id": f"{namespace}_role",
+                "class": f"pdp.handlers.{namespace}_handler.{_class_name(namespace, 'Handler')}",
+                "mode": "plugin",
+            }
+        ]
+    else:
+        caps["pdp_resource_handlers"] = []
+
+    if "config_pack" in surfaces or "policy_pack" in surfaces:
+        caps["config_packs"] = [
+            {"type": "applications", "ref": "pdp/config/applications.yaml"},
+            {"type": "policies", "ref": f"pdp/config/policies/applications/{name}/"},
+        ]
+
+    if "seed_data" in surfaces:
+        caps["seed_data"] = [
+            f"membership/seed/01_{namespace}_seed.cypher",
+        ]
+
+    if "experience_plugin" in surfaces:
+        caps["experience_plugins"] = [
+            {
+                "id": f"{name}-explorer",
+                "source": f"experience/{name}-explorer",
+                "build_command": "npm run build",
+                "bundle": f"experience/{name}-explorer/dist/index.esm.js",
+            }
+        ]
+
+    if "sidecar_adapter" in surfaces:
+        caps["sidecars"] = [
+            {
+                "id": f"{name}-gateway",
+                "compose_fragment": "deployment/docker-compose.sidecars.yml",
+                "neo4j_direct_access": False,
+            }
+        ]
+
+    content = "# Extension manifest — generated by `enow extension scaffold`\n"
+    content += yaml.dump(manifest, default_flow_style=False, sort_keys=False)
+    _write(root / "extension.yaml", content, result)
+
+
+def _scaffold_pdp_config(
+    root: Path, name: str, namespace: str, result: ScaffoldResult,
+) -> None:
+    policy_dir = _mk(root, "pdp", "config", "policies", "applications", name, result=result)
+
+    app_yaml = {
+        name: {
+            "description": f"PDP application for {name} extension",
+            "policy_set": f"applications/{name}",
+            "default_decision": "deny",
+        }
+    }
+    _write(
+        root / "pdp" / "config" / "applications.yaml",
+        yaml.dump(app_yaml, default_flow_style=False, sort_keys=False),
+        result,
+    )
+
+    sample_policy = {
+        "policy_id": f"{namespace}-sample-rule",
+        "description": f"Sample deny rule for {name}",
+        "target": {
+            "resource_type": f"{namespace}.entitlement",
+            "action": "can_access",
+        },
+        "rules": [
+            {
+                "effect": "deny",
+                "condition": {
+                    "operator": "not_equals",
+                    "left": {"path": "subject.properties.active"},
+                    "right": {"value": True},
+                },
+                "description": "Deny inactive users",
+            }
+        ],
+        "combining_algorithm": "deny-overrides",
+    }
+    _write(
+        policy_dir / f"{namespace}-sample.json",
+        _json_dumps(sample_policy),
+        result,
+    )
+
+
+def _scaffold_projections(
+    root: Path, namespace: str, result: ScaffoldResult,
+) -> None:
+    proj_dir = _mk(root, "membership", "projections", result=result)
+    cls_name = _class_name(namespace, "UserProjection")
+
+    content = f'''"""
+{cls_name} — user profile projection for the {namespace} extension.
+
+Replace the sample Cypher query with real attribute selections.
+"""
+
+
+class {cls_name}:
+    """Returns user profile data from the Membership graph."""
+
+    QUERY = """
+    MATCH (i:Identity {{id: $identity_id}})
+    OPTIONAL MATCH (i)-[:BELONGS_TO_ORG]->(o:OrgEntity)
+    RETURN i.id AS id,
+           i.display_name AS display_name,
+           i.email AS email,
+           i.status AS status,
+           o.name AS org_name
+    """
+
+    async def execute(self, identity_id: str, *, driver) -> dict | None:
+        """Run the projection query and return the result dict."""
+        async with driver.session() as session:
+            record = await session.run(self.QUERY, identity_id=identity_id)
+            row = await record.single()
+            if row is None:
+                return None
+            return dict(row)
+'''
+    _write(proj_dir / f"{namespace}_user_projection.py", content, result)
+
+
+def _scaffold_seed_data(
+    root: Path, namespace: str, result: ScaffoldResult,
+) -> None:
+    seed_dir = _mk(root, "membership", "seed", result=result)
+    content = f"""// Seed data for {namespace} extension
+// Run via: cypher-shell < 01_{namespace}_seed.cypher
+
+// Sample organization
+MERGE (o:OrgEntity {{id: "{namespace}-hq"}})
+SET o.name = "{namespace.title()} Headquarters",
+    o.status = "ACTIVE",
+    o.type = "CORPORATE";
+
+// Sample identity
+MERGE (i:Identity {{id: "{namespace}-admin-001"}})
+SET i.display_name = "Admin User",
+    i.email = "admin@{namespace}.example.com",
+    i.status = "ACTIVE";
+
+// Link identity to org
+MERGE (i)-[:BELONGS_TO_ORG]->(o)
+WHERE i.id = "{namespace}-admin-001" AND o.id = "{namespace}-hq";
+"""
+    _write(seed_dir / f"01_{namespace}_seed.cypher", content, result)
+
+
+def _scaffold_pip(
+    root: Path, namespace: str, result: ScaffoldResult,
+) -> None:
+    pip_dir = _mk(root, "pdp", "pips", result=result)
+    _write(pip_dir / "__init__.py", "", result)
+
+    cls_name = _class_name(namespace, "PIP")
+    content = f'''"""
+{cls_name} — Policy Information Point for {namespace} entitlements.
+
+Fetches entitlement catalog from a Membership projection so the PDP
+can evaluate subject eligibility against resource attributes.
+"""
+
+
+class {cls_name}:
+    """Provides resource attributes for {namespace}.entitlement evaluations."""
+
+    async def fetch(self, resource_id: str, *, context) -> dict:
+        """Return resource properties for the given entitlement."""
+        return {{
+            "id": resource_id,
+            "type": "{namespace}.entitlement",
+            "properties": {{}},
+        }}
+'''
+    _write(pip_dir / f"{namespace}_pip.py", content, result)
+
+
+def _scaffold_handler(
+    root: Path, namespace: str, result: ScaffoldResult,
+) -> None:
+    handler_dir = _mk(root, "pdp", "handlers", result=result)
+
+    cls_name = _class_name(namespace, "Handler")
+    content = f'''"""
+{cls_name} — PDP resource handler for {namespace} role derivation.
+"""
+
+
+class {cls_name}:
+    """Derives eligible roles for a subject using {namespace} policies."""
+
+    async def evaluate(self, subject: dict, *, context) -> list[dict]:
+        """Return list of eligible role assignments."""
+        return []
+'''
+    _write(handler_dir / f"{namespace}_handler.py", content, result)
+
+
+def _scaffold_experience_plugin(
+    root: Path, name: str, namespace: str, result: ScaffoldResult,
+) -> None:
+    plugin_dir = _mk(root, "experience", f"{name}-explorer", result=result)
+
+    package_json = {
+        "name": f"@empowernow/{name}-explorer",
+        "version": "1.0.0",
+        "private": True,
+        "scripts": {"build": "echo 'TODO: configure build'"},
+    }
+    _write(
+        plugin_dir / "package.json",
+        _json_dumps(package_json),
+        result,
+    )
+
+    _write(
+        plugin_dir / "src" / "index.tsx",
+        f'// {name}-explorer — EmpowerNow experience plugin\nexport default function App() {{\n  return <div>{namespace.title()} Explorer</div>;\n}}\n',
+        result,
+    )
+
+
+def _scaffold_sidecar(
+    root: Path, name: str, result: ScaffoldResult,
+) -> None:
+    deploy_dir = _mk(root, "deployment", result=result)
+
+    compose = {
+        "services": {
+            f"{name}-gateway": {
+                "build": {"context": f"../../{name}", "dockerfile": "deployment/Dockerfile"},
+                "ports": ["8090:8090"],
+                "environment": {"MEMBERSHIP_URL": "http://membership_app:8003"},
+            }
+        }
+    }
+    _write(
+        deploy_dir / "docker-compose.sidecars.yml",
+        yaml.dump(compose, default_flow_style=False, sort_keys=False),
+        result,
+    )
+
+    _write(
+        deploy_dir / "Dockerfile",
+        "FROM python:3.12-slim\nWORKDIR /app\nCOPY . .\nCMD [\"uvicorn\", \"app:app\", \"--host\", \"0.0.0.0\", \"--port\", \"8090\"]\n",
+        result,
+    )
+
+
+def _scaffold_tests(
+    root: Path, name: str, result: ScaffoldResult,
+) -> None:
+    test_dir = _mk(root, "tests", "e2e", result=result)
+    _write(test_dir / "__init__.py", "", result)
+
+    content = f'''"""
+Smoke tests for {name} extension.
+
+Run: pytest tests/e2e/ -v
+"""
+import pytest
+
+
+@pytest.mark.e2e
+class TestExtensionSmoke:
+    """Verify the extension deployed and basic services respond."""
+
+    def test_placeholder(self):
+        """Replace with real assertions once deployed."""
+        assert True, "Extension smoke test placeholder"
+'''
+    _write(test_dir / f"test_{name.replace('-', '_')}_e2e.py", content, result)
+
+
+def _class_name(namespace: str, suffix: str) -> str:
+    """Convert namespace to PascalCase and append suffix."""
+    parts = namespace.replace("-", "_").split("_")
+    return "".join(p.capitalize() for p in parts) + suffix
+
+
+def _json_dumps(obj: dict) -> str:
+    """JSON serialization with consistent formatting."""
+    import json
+    return json.dumps(obj, indent=2) + "\n"

enow_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: enow-cli
+Version: 0.1.0
+Summary: EmpowerNow extension deploy CLI — manifest-driven, cross-platform
+Requires-Python: >=3.11
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: click>=8.1
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-tmp-files>=0.0.2; extra == "dev"

enow_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+enow_cli/__init__.py,sha256=_McJEqfFOzWofy7S0qLsff_fza6_NkWD6tQlmCTe4aY,63
+enow_cli/deploy.py,sha256=4egGq3uZqTo1i7A6rASAZfBZARU2zAjsA789da6VDl8,9434
+enow_cli/main.py,sha256=06oQNJ_OAiTpyKMlfuOjPr-sZBo4xih_hQB61oXQs9E,7735
+enow_cli/manifest.py,sha256=YcwfJQH59zCJsKwH6sPbsTc29uVxfgaSEc2rl87YsPw,10011
+enow_cli/scaffold.py,sha256=z087biXGfdlgBael4dSxnyUxz8wAOb6vJ_P4eXR9Uw4,14148
+enow_cli-0.1.0.dist-info/METADATA,sha256=xNrFkDLRba7vmpa8vA0GdqjosT9_uWaDadgpCOhDUwg,324
+enow_cli-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+enow_cli-0.1.0.dist-info/entry_points.txt,sha256=4fUeNXDFPIbuIrOOblcummATC7--9XWzdRba3MlEuEY,43
+enow_cli-0.1.0.dist-info/top_level.txt,sha256=BEMh5pGP4vfWr-ag1_1Hp_2IPPYpxyspnHbEUmRNeN8,9
+enow_cli-0.1.0.dist-info/RECORD,,

enow_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

enow_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+enow = enow_cli.main:cli

enow_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+enow_cli