feat: add netengine init command to scaffold a new world spec

New users had no way to create a valid spec without hand-copying from
examples/. `netengine init` prompts for a world name and lifecycle mode,
writes a minimal but fully-valid YAML spec, and prints numbered next
steps so a fresh install can go from zero to `netengine up` in one
command.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01P4RwkvhxDXpypYHNiXWevp

Author: claude

netengine/cli/main.py

@@ -582,5 +582,198 @@ def _print_status(state: RuntimeState) -> None:
         click.echo(f"step-ca container: {state.step_ca_container_id}")
 
 
+_INIT_SPEC_TEMPLATE = """\
+metadata:
+  name: {name}
+  version: "1.0"
+  lifecycle: {lifecycle}
+
+substrate:
+  orchestrator: swarm
+  ntp:
+    enabled: true
+    servers:
+      - pool.ntp.org
+  networks:
+    platform:
+      type: bridge
+      subnet: 172.28.0.0/16
+      description: "Platform management network"
+    core:
+      type: bridge
+      subnet: 10.0.0.0/24
+      description: "In-world core network"
+  gateway:
+    platform_ip: 172.28.0.1
+    core_ip: 10.0.0.1
+    description: "Gateway stub"
+
+dns:
+  root:
+    enabled: true
+    type: authoritative
+    server: coredns
+    listen_ip: 10.0.0.2
+    soa_primary_ns: root.internal
+    soa_email: admin.internal
+    serial_policy: timestamp
+  platform_zone:
+    name: platform.internal
+    type: authoritative
+    listen_ip: 10.0.0.3
+  tlds:
+    - name: internal
+      description: "Default in-world TLD"
+      type: authoritative
+      listen_ip: 10.0.0.4
+
+pki:
+  root_ca:
+    cn: "{name} Root CA"
+    o: "{name}"
+    c: "US"
+    key_storage_mode: ephemeral
+    cert_lifetime_days: 3650
+  acme:
+    enabled: true
+    listen_ip: 10.0.0.6
+    canonical_name: ca.platform.internal
+  dnssec_enabled: true
+  dnssec_ksk_lifetime_days: 365
+  dnssec_zsk_lifetime_days: 30
+
+identity_platform:
+  oidc_provider: keycloak
+  listen_ip: 10.0.0.7
+  canonical_name: auth.platform.internal
+  realm_name: platform
+  admin_user:
+    username: admin
+    email: admin@platform.internal
+  scopes:
+    - "netengines:read"
+    - "netengines:write"
+    - "netengines:admin"
+
+world_registry:
+  enabled: true
+  listen_ip: 10.0.0.8
+  canonical_name: registry.platform.internal
+  organizations: []
+  operators: []
+  whois:
+    enabled: true
+    listen_ip: 10.0.0.9
+    port: 43
+
+domain_registry:
+  enabled: true
+  listen_ip: 10.0.0.10
+  canonical_name: domainreg.platform.internal
+  tld_delegations: []
+  address_space: []
+  registrar:
+    enabled: true
+    listen_ip: 10.0.0.11
+    canonical_name: registrar.platform.internal
+
+identity_inworld:
+  oidc_provider: keycloak
+  listen_ip: 10.0.0.12
+  canonical_name: auth.internal
+  realm_name: inworld
+  org_users: []
+  scopes:
+    - profile
+    - email
+    - openid
+
+ands:
+  profiles: {{}}
+  instances: []
+
+world_services:
+  mail:
+    enabled: false
+  storage:
+    enabled: false
+
+org_apps:
+  enabled: true
+  catalog: []
+  deployments: []
+
+gateway_portal:
+  enabled: true
+  real_internet:
+    mode: isolated
+  cross_world:
+    mode: none
+
+operator:
+  api:
+    enabled: true
+    listen_ip: 172.28.0.11
+    port: 8080
+    canonical_name: api.platform.internal
+  auth:
+    provider: oidc
+    issuer: "https://auth.platform.internal/realms/platform"
+    required_scope: "netengines:read"
+"""
+
+
+@cli.command()
+@click.option("--name", default=None, help="World name (e.g. my-world).")
+@click.option(
+    "--lifecycle",
+    type=click.Choice(["ephemeral", "persistent"]),
+    default=None,
+    help="World lifecycle mode.",
+)
+@click.option("--output", "-o", default=None, help="Output file path (default: <name>.yaml).")
+@click.option(
+    "--yes", "-y", is_flag=True, default=False, help="Accept all defaults without prompting."
+)
+def init(name: str | None, lifecycle: str | None, output: str | None, yes: bool) -> None:
+    """Scaffold a new world spec file and print next steps."""
+    if not name:
+        if yes:
+            name = "my-world"
+        else:
+            name = click.prompt("World name", default="my-world")
+
+    if not lifecycle:
+        if yes:
+            lifecycle = "ephemeral"
+        else:
+            lifecycle = click.prompt(
+                "Lifecycle",
+                type=click.Choice(["ephemeral", "persistent"]),
+                default="ephemeral",
+            )
+
+    out_path = Path(output) if output else Path(f"{name}.yaml")
+
+    if out_path.exists() and not yes:
+        click.confirm(f"{out_path} already exists — overwrite?", abort=True)
+
+    spec_content = _INIT_SPEC_TEMPLATE.format(name=name, lifecycle=lifecycle)
+    out_path.write_text(spec_content)
+
+    click.echo(f"\nCreated {out_path}\n")
+    click.echo("Next steps:\n")
+    click.echo("  1. Start a local Postgres + pgmq instance:")
+    click.echo("       docker compose up -d db\n")
+    click.echo("  2. Boot your world:")
+    click.echo(f"       netengine up {out_path}\n")
+    click.echo("  3. Check status at any time:")
+    click.echo("       netengine status\n")
+    click.echo("  4. Tear down when done:")
+    click.echo("       netengine down\n")
+    click.echo(f"Edit {out_path} to add orgs, ANDs, mail, storage, and more.")
+    click.echo("See examples/ for reference specs.")
+
+
 if __name__ == "__main__":
     cli()

tests/test_cli.py

@@ -6,6 +6,7 @@
 from unittest.mock import AsyncMock, patch
 
 import click
+import pytest
 from click.testing import CliRunner
 
 from netengine.cli import main as cli_main
@@ -86,6 +87,68 @@ def test_up_supports_environment_loader_option():
     mock_orchestrator.execute_phases.assert_awaited_once_with(up_to_phase=9)
 
 
+def test_init_creates_spec_file(tmp_path: Path) -> None:
+    """The init command should write a valid parseable spec and print next steps."""
+    from netengine.spec.loader import load_spec
+
+    out_file = tmp_path / "hello.yaml"
+    result = CliRunner().invoke(
+        cli_main.cli,
+        ["init", "--name", "hello", "--lifecycle", "ephemeral", "--output", str(out_file), "--yes"],
+    )
+
+    assert result.exit_code == 0, result.output
+    assert out_file.exists()
+    spec = load_spec(str(out_file))
+    assert spec.metadata.name == "hello"
+    assert "netengine up" in result.output
+    assert "netengine status" in result.output
+
+
+def test_init_uses_name_as_default_output_path(tmp_path: Path) -> None:
+    """Without --output the init command writes to <name>.yaml in cwd."""
+    import os
+
+    original_cwd = os.getcwd()
+    try:
+        os.chdir(tmp_path)
+        result = CliRunner().invoke(
+            cli_main.cli,
+            ["init", "--name", "my-world", "--lifecycle", "ephemeral", "--yes"],
+        )
+        assert result.exit_code == 0, result.output
+        assert (tmp_path / "my-world.yaml").exists()
+    finally:
+        os.chdir(original_cwd)
+
+
+def test_init_aborts_on_existing_file_without_yes(tmp_path: Path) -> None:
+    """Without --yes the init command should prompt before overwriting an existing file."""
+    out_file = tmp_path / "world.yaml"
+    out_file.write_text("original")
+
+    result = CliRunner().invoke(
+        cli_main.cli,
+        ["init", "--name", "world", "--lifecycle", "ephemeral", "--output", str(out_file)],
+        input="n\n",
+    )
+
+    assert result.exit_code != 0
+    assert out_file.read_text() == "original"
+
+
+@pytest.mark.parametrize("lifecycle", ["ephemeral", "persistent"])
+def test_init_lifecycle_propagates_to_spec(tmp_path: Path, lifecycle: str) -> None:
+    """The lifecycle flag should appear verbatim in the written spec."""
+    out_file = tmp_path / "world.yaml"
+    CliRunner().invoke(
+        cli_main.cli,
+        ["init", "--name", "world", "--lifecycle", lifecycle, "--output", str(out_file), "--yes"],
+    )
+    content = out_file.read_text()
+    assert f"lifecycle: {lifecycle}" in content
+
+
 def test_up_supports_repeatable_set_overrides():
     """The up command should pass repeatable dotted --set overrides into composition loading."""
     spec_file = Path(__file__).parent.parent / "examples" / "minimal.yaml"