******************************
* Bundle command lines e.g. *
******************************


[ Adding a new bundle ]

    Adding/importing bundle
    ----------

    To add a new bundle or to import an existing one, use the following command line.

    $ gina bundle:add <bundle_name> @<project_name>
    Or
    $ gina bundle:add <bundle_name> @<project_name> --start-port-from<port_number>


    Adding multiple
    ----------
    $ gina bundle:add <bundle_name_1> <bundle_name_2> <bundle_name_3> @<project_name>


    When the bundle already exists
    ----------
    You are prompted to replace, import, or cancel. Pass a flag to skip the
    prompt — required when running without an interactive terminal (container,
    CI, or piped stdin):

    $ gina bundle:add <bundle_name> @<project_name> --import     (register the existing source)
    $ gina bundle:add <bundle_name> @<project_name> --replace    (overwrite; existing files are lost)



[ Removing an existing bundle ]

    $ gina bundle:remove <bundle_name> @<project_name>



[ Copying a bundle under a new name ]

    Duplicate a bundle's source + config under a new name inside the SAME
    project. gina copies the source tree, rewrites the bundle-name footprint
    (controller class names, the gina require-var, app.json name, webroot) in
    the copied .js/.json files, allocates a fresh full protocol/scheme/env port
    matrix for the new name, and registers it in manifest.json + env.json +
    ~/.gina/ports.json. User content in templates / SQL / CSS is copied verbatim.

    $ gina bundle:copy <source_bundle_name> <new_bundle_name> @<project_name>

    Alias
    ----------
    $ gina bundle:cp <source_bundle_name> <new_bundle_name> @<project_name>

    Preview without writing anything
    ----------
    Lists every file the name rewrite would touch (and the planned port /
    manifest changes) so coincidental matches can be reviewed before any write.

    $ gina bundle:copy <source_bundle_name> <new_bundle_name> @<project_name> --dry-run
    $ gina bundle:copy <source_bundle_name> <new_bundle_name> @<project_name> --dry-run --format=json

    Overwrite an existing target
    ----------
    $ gina bundle:copy <source_bundle_name> <new_bundle_name> @<project_name> --force



[ Renaming a bundle ]

    Rename a bundle IN PLACE inside the SAME project. gina moves the source
    tree to the new name, rewrites the bundle-name footprint (controller class
    names, the gina require-var, app.json name, webroot) in the moved .js/.json
    files, and rekeys manifest.json + env.json + the ports registry to the new
    name. The existing port numbers are preserved (rekeyed, not reallocated).
    User content in templates / SQL / CSS is moved verbatim. The bundle must be
    stopped first.

    $ gina bundle:rename <old_bundle_name> <new_bundle_name> @<project_name>

    Preview without writing anything
    ----------
    Lists every file the name rewrite would touch so coincidental matches can be
    reviewed before any write.

    $ gina bundle:rename <old_bundle_name> <new_bundle_name> @<project_name> --dry-run
    $ gina bundle:rename <old_bundle_name> <new_bundle_name> @<project_name> --dry-run --format=json

    Overwrite an existing target
    ----------
    $ gina bundle:rename <old_bundle_name> <new_bundle_name> @<project_name> --force



[ Listing all bundles inside your project ]

    $ gina bundle:list @<project_name>

    or to list all projects bundles

    $ gina bundle:list


[ Showing a bundle's status ]

    $ gina bundle:status <bundle_name> @<project_name>

    or as JSON

    $ gina bundle:status <bundle_name> @<project_name> --format=json


[ Starting a bundle ]

    $ gina bundle:start <bundle_name> @<project_name>

    or to start more than one at once under the same project

    $ gina bundle:start <bundle_name_1> <bundle_name_2> @<project_name>

    [ Starting a bundle in debug mode ]

    $ gina bundle:start <bundle_name> @<project_name> --debug-brk=5656 --max-old-space-size=2048

    [ Starting a bundle pinned to a specific installed gina version ]

    $ gina bundle:start <bundle_name> @<project_name> --gina-version=0.1.8

    The declared version is validated against the tracked versions in ~/.gina/main.json.
    You can also pin a version statically in your project's manifest.json:

        "bundles": {
            "<bundle_name>": {
                "gina_version": "0.1.8",
                ...
            }
        }

    The CLI flag takes priority over the manifest.json declaration.
    The socket server keeps running its own version; only the spawned bundle process
    uses the declared version.


[ Stopping a bundle ]

    $ gina bundle:stop <bundle_name> @<project_name>


[ Stopping all your project bundles ]

    $ gina bundle:stop @<project_name>


[ Restarting a bundle ]

    $ gina bundle:restart <bundle_name> @<project_name>


[ Restarting all your project bundles ]

    $ gina bundle:restart @<project_name>


[ Generating OpenAPI spec ]

    Generate an OpenAPI 3.1.0 specification from routing.json for a bundle.
    The spec is written to <bundle>/config/openapi.json by default.

    $ gina bundle:openapi <bundle_name> @<project_name>

    Generate specs for all bundles in a project
    ----------
    $ gina bundle:openapi @<project_name>

    Write to a custom output path
    ----------
    $ gina bundle:openapi <bundle_name> @<project_name> --output=/path/to/spec.json

    Alias
    ----------
    $ gina bundle:oas <bundle_name> @<project_name>



[ Generating MCP tool manifest ]

    Generate a Model Context Protocol (MCP) tool manifest from routing.json
    for a bundle. The manifest targets MCP spec revision 2025-06-18 and is
    written to <bundle>/config/mcp.json by default.

    The emitted file is a static manifest — one tool per (route × URL
    variant × HTTP method) combination, with inputSchema derived from URL
    parameters and requirements. No runtime MCP server is started.

    $ gina bundle:mcp <bundle_name> @<project_name>

    Generate manifests for all bundles in a project
    ----------
    $ gina bundle:mcp @<project_name>

    Write to a custom output path
    ----------
    $ gina bundle:mcp <bundle_name> @<project_name> --output=/path/to/mcp.json



[ Starting an MCP server ]

    Run a live Model Context Protocol server for a single bundle over stdio
    (MCP spec revision 2025-06-18). Tool calls are dispatched over HTTP
    loopback to the running bundle. The bundle MUST already be started
    ($ gina bundle:start) and a manifest generated ($ gina bundle:mcp) — the
    server reads <bundle>/config/mcp.json to discover tools and warns on
    stderr if the manifest is older than routing.json.

    stdout is reserved for JSON-RPC frames; diagnostics are written to
    stderr so the wire stays clean for MCP clients.

    $ gina bundle:mcp-start <bundle_name> @<project_name>

    The bundle port is resolved from the live ports registry. If the bundle
    is not currently running, the server falls back to `mcp.json > server >
    baseUrl` and dispatch will fail loudly on ECONNREFUSED until the bundle
    comes up.

    Override the HTTP dispatch timeout (default 30 000 ms) for tighter CI
    or longer interactive sessions. Precedence: CLI flag > `mcp.json >
    server > timeoutMs` > default.

    $ gina bundle:mcp-start <bundle_name> @<project_name> --timeout-ms=5000


    [ MCP Streamable HTTP transport ]

    Switch the MCP wire from stdio to Streamable HTTP — for remote or
    containerised agents, or any client that cannot pipe stdio.

    $ gina bundle:mcp-start <bundle_name> @<project_name> --transport=http
    $ gina bundle:mcp-start <bundle_name> @<project_name> --transport=http --http-port=3107
    $ gina bundle:mcp-start <bundle_name> @<project_name> --transport=http --auth-token=<token>

    HTTP transport flags:
      --http-host=<host>       Bind host. Default: $GINA_HOST_V4 (from
                               ~/.gina/<shortVersion>/settings.json > host_v4,
                               normally 127.0.0.1). Pass 0.0.0.0 to expose
                               externally — deliberate opt-in.
      --http-port=<n>          Bind port. Default: 0 (OS-assigned; the
                               resolved port is logged to stderr on start).
      --max-in-flight=<n>      Concurrency cap on upstream dispatch.
                               Default: 16. Applies across all HTTP clients
                               sharing this transport.
      --auth-token=<token>     Require `Authorization: Bearer <token>` on
                               every non-OPTIONS request. Also readable
                               from `$GINA_MCP_AUTH_TOKEN` or
                               `mcp.json > server > authToken`.
      --cors-origin=<list>     Extra origins beyond the built-in loopback
                               allowlist (`http(s)://localhost`, `127.0.0.1`,
                               `[::1]` on any port). Comma-separated. Pass
                               `*` to disable the Origin check entirely.

    Default security posture — bind loopback, no auth, Origin allowlist
    accepts localhost / 127.0.0.1 / [::1] only. For OAuth-protected
    deployments, place gina behind a reverse proxy (oauth2-proxy, Traefik
    ForwardAuth, nginx `auth_request`) that handles the OAuth dance and
    forwards the upstream request.