guild-cli 0.7.3__tar.gz → 0.8.0__tar.gz

{guild_cli-0.7.3 → guild_cli-0.8.0}/.claude/skills/guild/scripts/create.sh

@@ -12,12 +12,20 @@ set -euo pipefail
 # Usage:
 #   create.sh --agent OWNER/REPO --desc TEXT [--backend claude|acp]
 #             [--workspace-root DIR] [--template OWNER/REPO]
-#             [--org agentculture] [--dist NAME] [--apply] [--json]
+#             [--org agentculture] [--command NAME] [--pkg NAME]
+#             [--dist NAME] [--apply] [--json]
 #
-# --dist NAME sets the PyPI distribution name (default: the repo name); pass
-#   e.g. --dist jetson-cli to ship the dist as jetson-cli while keeping the
-#   command + import package as the repo name. Retargets [project].name, the
-#   importlib.metadata lookup, and the TestPyPI install pin.
+# The repo name is the repo/agent identity (README, culture.yaml suffix,
+# CLAUDE.md seed, repo URL). --command / --pkg / --dist each retarget one facet
+# independently and default to the repo name (or, for --pkg, the underscore form
+# of --command), so with no overrides the result is identical to before:
+#   --command NAME  console-command name (the [project.scripts] key only); e.g.
+#                   --command reachy for a repo reachy-mini-cli.
+#   --pkg NAME      importable package; defaults to the underscore form of
+#                   --command (pass only to decouple command from package).
+#   --dist NAME     PyPI distribution name; e.g. --dist jetson-cli. Retargets
+#                   [project].name, the importlib.metadata lookup, and the
+#                   TestPyPI install pin.
 #
 # Exit codes:
 #   0   success (delegates to `guild create`; its exit code propagates)

{guild_cli-0.7.3 → guild_cli-0.8.0}/CHANGELOG.md

@@ -5,6 +5,38 @@ All notable changes to this project will be documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/). This project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.8.0] - 2026-05-30
+
+### Added
+
+- **`guild create`: repo≠command split via `--command` / `--pkg`**
+  ([#43](https://github.com/agentculture/guildmaster/issues/43)). A new sibling
+  can now ship its CLI under a shorter name than the repo — the guildmaster
+  pattern (repo `guildmaster` → command/package `guild` → dist `guild-cli`) —
+  without a manual post-create edit.
+  - `--command NAME` sets the console-command (binary) name (default: the repo
+    token) and retargets **only** the `[project.scripts]` entry-point key.
+  - `--pkg NAME` sets the importable Python package (default: the underscore
+    form of `--command`, so command + import package stay in lock-step); pass it
+    only to decouple the two.
+  - The **repo token stays the repo/agent identity** (README heading,
+    `culture.yaml` suffix, CLAUDE.md seed, repo URL). `--command` / `--pkg` /
+    `--dist` are each independent; with no overrides the output is byte-identical
+    to before.
+  - Validation is fail-fast (before any external act): `--command` must be a PEP
+    503-ish name and the *effective* import package must be a valid, non-keyword
+    Python identifier (the error attributes the bad value to `--pkg`, else
+    `--command`, else the repo name).
+  - A `--dist`/`--command` rename still does **not** register a PyPI/TestPyPI
+    Trusted Publisher — `guild create` configures only the GitHub side.
+  - Pure transform: new `_resolve_identifiers` (single source of truth shared by
+    `transform_plan` / `transform_clone`) and `_retarget_command` (narrow
+    scripts-key rewrite, mirroring `_retarget_dist`).
+
+### Changed
+
+### Fixed
+
 ## [0.7.3] - 2026-05-29
 
 ### Added

{guild_cli-0.7.3 → guild_cli-0.8.0}/CLAUDE.md

@@ -108,7 +108,7 @@ two live broadcasters.
 
 **Provisioning verb — `guild create` (template-instantiate a new sibling).**
 
-- `guild create --agent OWNER/REPO --desc TEXT [--backend claude|acp] [--workspace-root DIR] [--template agentculture/culture-agent-template] [--dist NAME] [--apply] [--json]` — provision a brand-new AgentCulture sibling by instantiating the GitHub template, renaming identifiers throughout the clone, writing a self-init CLAUDE.md seed, configuring the GitHub repo (branch protection, environments, SONAR_TOKEN placeholder), pushing the genesis commit, and registering the agent in `docs/skill-sources.md`. Dry-run by default; `--apply` executes. The transform is **pure** (unit-testable against a fixture dir; no network): `culture_agent_template` → pkg (underscore form, e.g. `my_agent`), `culture-agent-template` → repo token (hyphen form, e.g. `my-agent`). `--dist NAME` sets the **PyPI distribution name** (default: the repo token); pass e.g. `--dist jetson-cli` to publish as `jetson-cli` while keeping the command and import package as the repo token (`jetson`) — this retargets only `[project].name`, the `importlib.metadata` lookup, and the TestPyPI install pin, matching the `guild-cli`/`guild` convention without a manual post-create edit. (Renaming the dist needs a matching Trusted Publisher registered for that project name on PyPI/TestPyPI — `guild create` configures the GitHub side only.) The CLAUDE.md seed is a `/init`-style bootstrap placeholder — run `/init` in the new repo after provisioning to expand it into a full runtime prompt. Implementation: `guild/scaffold/instantiate.py` (pure transform), `guild/cli/_commands/create.py` (CLI), `guild/cli/_commands/_provision_template.py` (injectable-runner executor), `.claude/skills/guild/scripts/create.sh` (thin wrapper).
+- `guild create --agent OWNER/REPO --desc TEXT [--backend claude|acp] [--workspace-root DIR] [--template agentculture/culture-agent-template] [--command NAME] [--pkg NAME] [--dist NAME] [--apply] [--json]` — provision a brand-new AgentCulture sibling by instantiating the GitHub template, renaming identifiers throughout the clone, writing a self-init CLAUDE.md seed, configuring the GitHub repo (branch protection, environments, SONAR_TOKEN placeholder), pushing the genesis commit, and registering the agent in `docs/skill-sources.md`. Dry-run by default; `--apply` executes. The transform is **pure** (unit-testable against a fixture dir; no network): `culture_agent_template` → pkg (underscore form, e.g. `my_agent`), `culture-agent-template` → repo token (hyphen form, e.g. `my-agent`). **The repo token is the repo/agent identity only** — it always drives the README heading, `culture.yaml` suffix, CLAUDE.md seed, and repo URL. The **command**, **import package**, and **dist** are each independently retargetable and default to the repo token (or, for `--pkg`, the underscore form of `--command`); with no overrides the output is byte-identical to a plain rename. `--command NAME` sets the **console-command (binary) name** (default: the repo token) and retargets **only** the `[project.scripts]` entry-point key — e.g. `--command reachy` for repo `reachy-mini-cli` ships the command as `reachy`. `--pkg NAME` sets the **importable Python package** (default: the underscore form of `--command`, so command and import package stay in lock-step like `guild`/`guild`); pass it only to decouple the two. `--dist NAME` sets the **PyPI distribution name** (default: the repo token); pass e.g. `--dist jetson-cli` to publish as `jetson-cli` while keeping the command and import package as the repo token (`jetson`) — this retargets only `[project].name`, the `importlib.metadata` lookup, and the TestPyPI install pin, matching the `guild-cli`/`guild` convention without a manual post-create edit. (Renaming the dist or command does **not** register a Trusted Publisher — that needs a matching Trusted Publisher registered for the project name on PyPI/TestPyPI; `guild create` configures the GitHub side only.) The CLAUDE.md seed is a `/init`-style bootstrap placeholder — run `/init` in the new repo after provisioning to expand it into a full runtime prompt. Implementation: `guild/scaffold/instantiate.py` (pure transform: `_resolve_identifiers` + `_retarget_command` / `_retarget_dist`), `guild/cli/_commands/create.py` (CLI), `guild/cli/_commands/_provision_template.py` (injectable-runner executor), `.claude/skills/guild/scripts/create.sh` (thin wrapper).
 
 **Inventory verbs — `overview` & `show` (the read-only surfaces).** guildmaster
 owns the mesh's *inventory* surfaces per

{guild_cli-0.7.3 → guild_cli-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: guild-cli
-Version: 0.7.3
+Version: 0.8.0
 Summary: guildmaster — an agent and CLI that manages skills for the AgentCulture mesh.
 Project-URL: Homepage, https://github.com/agentculture/guildmaster
 Project-URL: Issues, https://github.com/agentculture/guildmaster/issues

{guild_cli-0.7.3 → guild_cli-0.8.0}/guild/cli/_commands/_provision_template.py

@@ -242,6 +242,8 @@ def apply(
     runner: Runner | None = None,
     template: str = DEFAULT_TEMPLATE,
     dist: str | None = None,
+    command: str | None = None,
+    pkg: str | None = None,
     poll_attempts: int = 30,
     poll_delay: float = 2.0,
 ) -> dict:
@@ -269,6 +271,12 @@ def apply(
     dist:
         PyPI distribution name to set in the clone. ``None`` leaves it as the
         repo name; a different value retargets the dist (see ``transform_clone``).
+    command:
+        Console-command name to set in the clone. ``None`` leaves it as the repo
+        name; a different value retargets the ``[project.scripts]`` key.
+    pkg:
+        Importable package name. ``None`` defaults to the underscore form of the
+        effective command (see ``transform_clone``).
     poll_attempts / poll_delay:
         ``gh repo create --template`` copies the template content
         **asynchronously**; cloning immediately yields an empty repo. After
@@ -319,7 +327,7 @@ def apply(
     _check(clone, f"git clone {agent} failed", EXIT_ENV_ERROR)
 
     # Step 4 — pure transform (no runner needed).
-    transform_clone(clone_dest, bare, desc, backend, dist=dist)
+    transform_clone(clone_dest, bare, desc, backend, dist=dist, command=command, pkg=pkg)
 
     # Step 5 — stage everything.
     add = runner(["git", "-C", str(clone_dest), "add", "-A"])

{guild_cli-0.7.3 → guild_cli-0.8.0}/guild/cli/_commands/create.py

@@ -15,7 +15,8 @@ Usage
     guild create --agent OWNER/REPO --desc TEXT [--org agentculture]
                  [--backend claude|acp] [--workspace-root DIR]
                  [--template agentculture/culture-agent-template]
-                 [--dist NAME] [--apply] [--json]
+                 [--command NAME] [--pkg NAME] [--dist NAME]
+                 [--apply] [--json]
 """
 
 from __future__ import annotations
@@ -35,6 +36,11 @@ from guild.cli._repo import repo_root
 from guild.scaffold.instantiate import transform_plan as _transform_plan
 from guild.skills import ledger as _ledger
 
+# A PEP 503-ish name: a non-empty run of letters/digits/.-_ that starts and ends
+# alphanumerically. PyPI normalises [-_.] runs, but the raw value must still look
+# like a name. Shared by the --dist and --command validators.
+_PEP503 = re.compile(r"^[A-Za-z0-9]([A-Za-z0-9._-]*[A-Za-z0-9])?$")
+
 
 def register(sub: argparse._SubParsersAction) -> None:
     parser = sub.add_parser(
@@ -87,6 +93,30 @@ def register(sub: argparse._SubParsersAction) -> None:
         default=_provision.DEFAULT_TEMPLATE,
         help=f"GitHub template repo to instantiate (default: {_provision.DEFAULT_TEMPLATE}).",
     )
+    parser.add_argument(
+        "--command",
+        # Explicit dest: the bare "command" dest collides with the subparsers'
+        # ``dest="command"`` (which holds the chosen subcommand name).
+        dest="command_name",
+        metavar="NAME",
+        default=None,
+        help=(
+            "Console-command (binary) name. Defaults to the repo name; pass e.g. "
+            "'reachy' for a repo 'reachy-mini-cli' to ship the command as 'reachy'. "
+            "Retargets only the [project.scripts] entry-point key. The import "
+            "package follows it (underscore form) unless --pkg overrides."
+        ),
+    )
+    parser.add_argument(
+        "--pkg",
+        metavar="NAME",
+        default=None,
+        help=(
+            "Importable Python package name. Defaults to the underscore form of "
+            "--command, so command and import package stay in lock-step (like "
+            "guild/guild). Pass it only to decouple the two."
+        ),
+    )
     parser.add_argument(
         "--dist",
         metavar="NAME",
@@ -115,50 +145,77 @@ def register(sub: argparse._SubParsersAction) -> None:
 
 
 # ---------------------------------------------------------------------------
-# Handler
+# Validation (fail-fast, before any external act)
 # ---------------------------------------------------------------------------
 
 
-def _handle(args: argparse.Namespace) -> None:
-    root = repo_root()
-    agent = _broadcast.normalize_target(args.agent, args.org)
-    bare = agent.rsplit("/", 1)[-1]
-
-    # Fail fast (before any external act) if the repo name can't derive a valid
-    # Python package identifier — the derived pkg is both a directory name and a
-    # global rename token, so an invalid value (dots, leading digit) breaks the
-    # generated sibling.
-    pkg = bare.lower().replace("-", "_")
-    if not pkg.isidentifier() or keyword.iskeyword(pkg):
+def _validate_pep503(value: str | None, flag: str, what: str, example: str) -> None:
+    """Reject *value* (when given) if it is not a PEP 503-ish name."""
+    if value is not None and not _PEP503.match(value):
         raise GuildError(
             code=EXIT_USER_ERROR,
-            message=f"repo name {bare!r} derives an invalid Python package name {pkg!r}",
+            message=f"{flag} {value!r} is not a valid {what}",
             remediation=(
-                "use a repo name of letters/digits/hyphens that maps to a valid, "
-                "non-keyword Python identifier (e.g. not starting with a digit)"
+                "use letters/digits/.-_ starting and ending alphanumerically " f"(e.g. {example!r})"
             ),
         )
 
-    # Validate the optional PyPI dist name (fail fast, before any external act).
-    # PyPI normalises [-_.] runs, but the raw name must still be a non-empty run
-    # of letters/digits/.-_ that starts and ends alphanumerically (PEP 503).
-    if args.dist is not None and not re.match(
-        r"^[A-Za-z0-9]([A-Za-z0-9._-]*[A-Za-z0-9])?$", args.dist
-    ):
+
+def _effective_pkg_for_validation(args: argparse.Namespace, repo_token: str) -> str:
+    """Mirror the resolver: the import package the transform will actually use."""
+    effective_command = args.command_name if args.command_name is not None else repo_token
+    return args.pkg if args.pkg is not None else effective_command.replace("-", "_")
+
+
+def _validate_identifiers(args: argparse.Namespace, bare: str, repo_token: str) -> None:
+    """Fail-fast validation of --command / --pkg / --dist before any external act.
+
+    The *effective* import package is both a directory name and a global rename
+    token, so an invalid value (dots, leading digit, keyword) breaks the
+    generated sibling. Attribute a bad value to --pkg, else --command, else the
+    repo name.
+    """
+    _validate_pep503(args.command_name, "--command", "command name", "reachy")
+
+    effective_pkg = _effective_pkg_for_validation(args, repo_token)
+    if not effective_pkg.isidentifier() or keyword.iskeyword(effective_pkg):
+        if args.pkg is not None:
+            source = f"--pkg {args.pkg!r}"
+        elif args.command_name is not None:
+            source = f"--command {args.command_name!r}"
+        else:
+            source = f"repo name {bare!r}"
         raise GuildError(
             code=EXIT_USER_ERROR,
-            message=f"--dist {args.dist!r} is not a valid PyPI distribution name",
+            message=f"{source} derives an invalid Python package name {effective_pkg!r}",
             remediation=(
-                "use letters/digits/.-_ starting and ending alphanumerically (e.g. 'jetson-cli')"
+                "the import package must be a valid, non-keyword Python identifier "
+                "(letters/digits/underscore, not starting with a digit); pass --pkg to set it"
             ),
         )
 
+    _validate_pep503(args.dist, "--dist", "PyPI distribution name", "jetson-cli")
+
+
+# ---------------------------------------------------------------------------
+# Handler
+# ---------------------------------------------------------------------------
+
+
+def _handle(args: argparse.Namespace) -> None:
+    root = repo_root()
+    agent = _broadcast.normalize_target(args.agent, args.org)
+    bare = agent.rsplit("/", 1)[-1]
+    repo_token = bare.lower()
+
+    _validate_identifiers(args, bare, repo_token)
+
     # Resolve workspace root (parent of guildmaster if not supplied).
     workspace_root = args.workspace_root if args.workspace_root is not None else root.parent
     clone_dest = workspace_root / bare
 
     # Build the dry-run plan (pure — no writes, no subprocess).
-    plan = _transform_plan(bare, args.desc, dist=args.dist)
+    plan = _transform_plan(bare, args.desc, dist=args.dist, command=args.command_name, pkg=args.pkg)
 
     # Ledger diff (pure — reads only).
     skills = _broadcast.canonical_skills(root)
@@ -198,6 +255,8 @@ def _handle(args: argparse.Namespace) -> None:
         guildmaster_root=root,
         template=args.template,
         dist=args.dist,
+        command=args.command_name,
+        pkg=args.pkg,
     )
 
     # Register in the ledger idempotently.
@@ -213,6 +272,8 @@ def _handle(args: argparse.Namespace) -> None:
         "repo": apply_result["repo"],
         "clone_dest": apply_result["clone_dest"],
         "pushed": apply_result["pushed"],
+        "command": plan["command"],
+        "pkg": plan["pkg"],
         "dist": plan["dist"],
         "ledger_written": ledger_written,
     }
@@ -233,10 +294,10 @@ def _render_dry_run(result: dict) -> str:
         f"  agent      : {result['agent']}",
         f"  backend    : {result['backend']}",
         f"  clone dest : {result['clone_dest']}",
-        f"  pkg        : {plan['pkg']}",
-        f"  repo token : {plan['repo_token']}",
-        f"  dist (PyPI): {plan['dist']}"
-        + ("" if plan["dist"] == plan["repo_token"] else "  (command + import stay repo token)"),
+        f"  repo token : {plan['repo_token']}  (identity: README, culture.yaml, seed, URL)",
+        f"  command    : {plan['command']}",
+        f"  pkg import : {plan['pkg']}",
+        f"  dist (PyPI): {plan['dist']}",
         "",
         "── rename map ──",
     ]

{guild_cli-0.7.3 → guild_cli-0.8.0}/guild/scaffold/__init__.py

@@ -8,7 +8,7 @@ new sibling agent.
 Public surface
 --------------
 ``instantiate`` — the transform module:
-    transform_clone(dest, pkg, repo_token, desc, backend) -> None
-    rename_map(bare) -> dict[str, str]
-    transform_plan(bare, desc) -> dict
+    transform_clone(dest, bare, desc, backend="claude", dist=None, command=None, pkg=None) -> None
+    rename_map(bare, pkg=None) -> dict[str, str]
+    transform_plan(bare, desc, dist=None, command=None, pkg=None) -> dict
 """