yjcli 0.0.2__tar.gz → 0.0.3__tar.gz

{yjcli-0.0.2 → yjcli-0.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: yjcli
-Version: 0.0.2
+Version: 0.0.3
 Summary: Scaffold platforms, services, and AI agent wiring (Cursor/Claude) for YJ architecture repos.
 Project-URL: Homepage, https://github.com/yseiren87/yjcli
 Project-URL: Repository, https://github.com/yseiren87/yjcli
@@ -37,13 +37,13 @@ uv run yjcli --help
 uv run yjcli --version
 ```
 
-Version: `pyproject.toml` / `src/yjcli/__init__.py`.
+Version: `pyproject.toml` `[project].version` only (`yjcli --version` reads package metadata).
 
 ## Commands
 
 ```bash
 # Bootstrap: AGENTS.md/CLAUDE.md, .cursor/.claude skills+rules,
-# root Makefile/.gitignore, selected platform roots.
+# root Makefile/TOOLS.md/.gitignore, selected platform roots.
 uv run yjcli init
 uv run yjcli init --all
 uv run yjcli init -p backend -p frontend
@@ -56,5 +56,12 @@ uv run yjcli add platform -p cli
 uv run yjcli add service               # interactive
 uv run yjcli add service -p backend -n api
 
+uv run yjcli sync agents               # AGENTS.md → CLAUDE.md
+uv run yjcli sync skills               # packaged skills → .cursor/.claude
+uv run yjcli sync rules                # packaged rules → .cursor/.claude
+uv run yjcli sync all                  # agents + skills + rules
 uv run yjcli doctor                    # packaged asset sanity check
 ```
+
+Edit `AGENTS.md` only; run `yjcli sync agents` (or `sync all`) to refresh `CLAUDE.md`.
+

{yjcli-0.0.2 → yjcli-0.0.3}/README.md

@@ -12,13 +12,13 @@ uv run yjcli --help
 uv run yjcli --version
 ```
 
-Version: `pyproject.toml` / `src/yjcli/__init__.py`.
+Version: `pyproject.toml` `[project].version` only (`yjcli --version` reads package metadata).
 
 ## Commands
 
 ```bash
 # Bootstrap: AGENTS.md/CLAUDE.md, .cursor/.claude skills+rules,
-# root Makefile/.gitignore, selected platform roots.
+# root Makefile/TOOLS.md/.gitignore, selected platform roots.
 uv run yjcli init
 uv run yjcli init --all
 uv run yjcli init -p backend -p frontend
@@ -31,5 +31,12 @@ uv run yjcli add platform -p cli
 uv run yjcli add service               # interactive
 uv run yjcli add service -p backend -n api
 
+uv run yjcli sync agents               # AGENTS.md → CLAUDE.md
+uv run yjcli sync skills               # packaged skills → .cursor/.claude
+uv run yjcli sync rules                # packaged rules → .cursor/.claude
+uv run yjcli sync all                  # agents + skills + rules
 uv run yjcli doctor                    # packaged asset sanity check
 ```
+
+Edit `AGENTS.md` only; run `yjcli sync agents` (or `sync all`) to refresh `CLAUDE.md`.
+

{yjcli-0.0.2 → yjcli-0.0.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "yjcli"
-version = "0.0.2"
+version = "0.0.3"
 description = "Scaffold platforms, services, and AI agent wiring (Cursor/Claude) for YJ architecture repos."
 readme = "README.md"
 requires-python = ">=3.12"

{yjcli-0.0.2 → yjcli-0.0.3}/src/yjcli/__init__.py

@@ -1,3 +1 @@
 """yjcli — platform/service scaffold and agent wiring."""
-
-__version__ = "0.0.1"

{yjcli-0.0.2 → yjcli-0.0.3}/src/yjcli/cli.py

@@ -2,25 +2,38 @@
 
 from __future__ import annotations
 
+from importlib.metadata import PackageNotFoundError, version
 from typing import Optional
 
 import typer
 
-from yjcli import __version__
 from yjcli.commands import add
+from yjcli.commands import sync
 from yjcli.commands.init_cmd import init_cmd
 from yjcli.services import status
 
+
+def package_version() -> str:
+    """Installed package version from pyproject metadata (single source)."""
+    try:
+        return version("yjcli")
+    except PackageNotFoundError:
+        return "0.0.0+local"
+
+
+_HELP_CONTEXT = {"help_option_names": ["-h", "--help"]}
+
 app = typer.Typer(
     name="yjcli",
     help="Scaffold YJ platforms/services and Cursor/Claude agent wiring.",
     no_args_is_help=True,
+    context_settings=_HELP_CONTEXT,
 )
 
 
 def _version_callback(value: bool) -> None:
     if value:
-        typer.echo(__version__)
+        typer.echo(package_version())
         raise typer.Exit()
 
 
@@ -40,6 +53,7 @@ def main(
 
 app.command("init")(init_cmd)
 app.add_typer(add.app, name="add")
+app.add_typer(sync.app, name="sync")
 
 
 @app.command("doctor")

{yjcli-0.0.2 → yjcli-0.0.3}/src/yjcli/commands/add.py

@@ -10,7 +10,10 @@ import typer
 from yjcli.modules.constants import PLATFORMS
 from yjcli.services import scaffold
 
-app = typer.Typer(help="Add a platform or service to the current repo.")
+app = typer.Typer(
+    help="Add a platform or service to the current repo.",
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
 
 
 @app.command("platform")

yjcli-0.0.3/src/yjcli/commands/sync.py

@@ -0,0 +1,75 @@
+"""yjcli sync <what> — refresh agent docs / skills / rules."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from yjcli.services import sync as sync_svc
+
+app = typer.Typer(
+    help="Sync AGENTS.md mirror, skills, or rules into the target repo.",
+    no_args_is_help=True,
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+
+
+@app.command("agents")
+def sync_agents(
+    path: Path = typer.Option(
+        Path("."),
+        "--path",
+        help="Target repository root (default: cwd).",
+        file_okay=False,
+        dir_okay=True,
+        resolve_path=True,
+    ),
+) -> None:
+    """Overwrite CLAUDE.md from AGENTS.md (edit AGENTS.md only)."""
+    sync_svc.sync_agents(path)
+
+
+@app.command("skills")
+def sync_skills(
+    path: Path = typer.Option(
+        Path("."),
+        "--path",
+        help="Target repository root (default: cwd).",
+        file_okay=False,
+        dir_okay=True,
+        resolve_path=True,
+    ),
+) -> None:
+    """Overwrite .cursor/.claude skills from the yjcli package."""
+    sync_svc.sync_skills(path, force=True)
+
+
+@app.command("rules")
+def sync_rules(
+    path: Path = typer.Option(
+        Path("."),
+        "--path",
+        help="Target repository root (default: cwd).",
+        file_okay=False,
+        dir_okay=True,
+        resolve_path=True,
+    ),
+) -> None:
+    """Overwrite .cursor/.claude rules from the yjcli package."""
+    sync_svc.sync_rules(path, force=True)
+
+
+@app.command("all")
+def sync_all(
+    path: Path = typer.Option(
+        Path("."),
+        "--path",
+        help="Target repository root (default: cwd).",
+        file_okay=False,
+        dir_okay=True,
+        resolve_path=True,
+    ),
+) -> None:
+    """Sync AGENTS.md → CLAUDE.md, skills, and rules together."""
+    sync_svc.sync_all(path, force=True)

{yjcli-0.0.2 → yjcli-0.0.3}/src/yjcli/data/templates/AGENTS.md

@@ -10,9 +10,21 @@
 
 ## 2. Repository layout
 
+Paths from `yjcli init` are fixed; add platform/app rows with `<path>` / `<role>` as needed.
+
 | Path | Role |
 |------|------|
-| `<path>/` | `<role>` |
+| `AGENTS.md` | Agent / contributor guide (this file) |
+| `CLAUDE.md` | Mirror of `AGENTS.md` — do not edit; refresh with `yjcli sync agents` |
+| `TOOLS.md` | Release-tools feature spec (version / deploy / git) |
+| `Makefile` | Root run entry (`make run PLATFORM=… NAME=…`) |
+| `make.bat` | Windows counterpart of root Makefile |
+| `.gitignore` | Canonical ignore rules |
+| `.cursor/skills/` | Cursor skills (copied from package) |
+| `.cursor/rules/` | Cursor rules (copied from package) |
+| `.claude/skills/` | Claude skills (copied from package) |
+| `.claude/rules/` | Claude rules (copied from package) |
+| `.claude/settings.json` | Claude settings |
 | `<path>/` | `<role>` |
 | `<path>/` | `<role>` |
 
@@ -105,5 +117,6 @@
 
 | Kind | Location |
 |------|----------|
+| Release tools spec | `TOOLS.md` |
 | `<kind>` | `<path>` |
 | `<kind>` | `<path>` |

yjcli-0.0.3/src/yjcli/data/templates/TOOLS.md

@@ -0,0 +1,168 @@
+# TOOLS.md — Release tools (feature spec)
+
+Language-agnostic **feature specification** for local release tooling.  
+Not an architecture diary and not tied to a specific stack.
+
+**How to use**
+
+1. Keep or copy this file into a repo.
+2. Fill project-specific facts in §0 (inputs).
+3. Ask an agent/dev: *Implement TOOLS.md using \<language/toolchain\>.*
+4. Implementation may be Make + scripts, a small CLI, CI jobs, etc. — as long as behaviors below are met.
+
+---
+
+## 0. Project inputs (fill before implement)
+
+| ID | Input | Value |
+|----|--------|--------|
+| I1 | Product / package name | `<name>` |
+| I2 | Canonical version location | `<file + field>` — semver `X.Y.Z` |
+| I3 | Other version mirrors (optional) | `<paths or none>` |
+| I4 | Git root | `<path>` |
+| I5 | Default branch | `<branch>` |
+| I6 | Git remote name + URL | `<origin + url>` |
+| I7 | Production publish target | `<registry/host + package id>` |
+| I8 | Staging publish target (optional) | `<or none>` |
+| I9 | Secrets store | `<e.g. ignored .env path>` |
+| I10 | Secret: publish token name(s) | `<ENV keys>` |
+| I11 | Secret: git push token name (if HTTPS PAT) | `<ENV key or none if SSH>` |
+| I12 | Version tag pattern | `<e.g. vX.Y.Z or release/X.Y.Z>` |
+| I13 | Preferred invoke style | `<make / cli / npm scripts / …>` |
+
+---
+
+## 1. Goals
+
+Provide three capabilities, invocable from a single local entry surface (I13):
+
+| ID | Capability | Intent |
+|----|------------|--------|
+| C1 | **Version** | Read/bump canonical semver; keep mirrors in sync if any |
+| C2 | **Deploy** | Build and publish artifacts to configured targets |
+| C3 | **Git release** | Commit (optional), tag, push using non-interactive auth when scripted |
+
+Out of scope: app business logic, scaffold of product code, editor agent rules (see `AGENTS.md`).
+
+---
+
+## 2. Shared requirements
+
+| ID | Requirement |
+|----|-------------|
+| S1 | No secrets in git. Tokens only via I9/I10/I11. |
+| S2 | Destructive steps (publish, push, tag) require explicit confirmation, default **No**. |
+| S3 | User can abort the whole flow with a clear cancel word (recommend `exit`) on any prompt. |
+| S4 | Steps are logged with clear section boundaries (readable in a terminal). |
+| S5 | Missing config/secrets → fail with actionable message (what to set, where). |
+| S6 | Do not force-overwrite existing git tags matching I12 unless the project explicitly opts in (default: **fail**). |
+
+---
+
+## 3. C1 — Version management
+
+### 3.1 Behaviors
+
+| ID | Behavior |
+|----|----------|
+| V1 | Read version from I2; must match `X.Y.Z`. |
+| V2 | Support bumps: `major` → `X+1.0.0`, `minor` → `X.Y+1.0`, `fix` → `X.Y.Z+1`. |
+| V3 | After bump, write I2; if I3 is non-empty, update those to the same version. |
+| V4 | Optional: show latest version from production target I7 when query is possible; if unavailable, warn and continue. |
+| V5 | Interactive bump: ask whether to bump; if yes, ask `major`/`minor`/`fix` (invalid/empty → re-ask; cancel per S3). |
+| V6 | Non-interactive mode (optional): accept bump kind via flags/env; do not hang on stdin. |
+
+### 3.2 Acceptance
+
+- Given I2 = `1.2.3`, bump `fix` → I2 (and I3) become `1.2.4`.
+- Invalid version string in I2 → hard fail before publish/tag.
+
+---
+
+## 4. C2 — Deploy / publish
+
+### 4.1 Behaviors
+
+| ID | Behavior |
+|----|----------|
+| D1 | **Test**: run project-defined verification before publish (unit/smoke/e2e — project chooses). Fail stops the pipeline. |
+| D2 | **Build**: produce publishable artifact(s) for I7 (and I8 if used). |
+| D3 | **Validate** (recommended): dry-run or registry check when the ecosystem supports it. |
+| D4 | **Confirm** then **Publish** to I7 using I10. Default confirm = No. |
+| D5 | Provide a **staging path** when I8 exists: publish to I8 without requiring a version bump or git push (unless project opts in). |
+| D6 | Production path may optionally chain into C3 after successful publish (project chooses). |
+
+### 4.2 Acceptance
+
+- Failed D1 or D2 → no publish.
+- Declined confirm → no publish, exit cleanly.
+- Missing I10 → fail per S5.
+
+---
+
+## 5. C3 — Git release (push / tag)
+
+### 5.1 Behaviors
+
+| ID | Behavior |
+|----|----------|
+| G1 | Operate only on git root I4. |
+| G2 | Show status: branch, remote I6, current version (I2), whether tag I12(version) exists. |
+| G3 | **Commit** (optional): if working tree dirty, ask to commit; require non-empty message; cancel per S3. If clean, skip. |
+| G4 | **Tag**: create tag from I12 + current I2 version; if exists → fail (S6). |
+| G5 | **Push**: push current branch + new tag to I6. |
+| G6 | Auth: non-interactive for scripted use (PAT from I11 for HTTPS, or SSH agent). Do not open browser login flows in the happy path. |
+| G7 | Never persist raw tokens into remote URLs in git config. |
+
+### 5.2 Acceptance
+
+- Clean tree + new version tag → tag created and pushed when confirmed.
+- Existing tag → fail, no force-push by default.
+- Missing I11 when HTTPS PAT is required → fail per S5.
+
+---
+
+## 6. Suggested entry surface (names are free)
+
+Implementers pick I13 names; map behaviors roughly like:
+
+| Entry | Calls |
+|-------|--------|
+| Help | List entries |
+| Version / bump | C1 |
+| Deploy production | C1 (optional ask) → C2 → optional C3 |
+| Deploy staging | C2 against I8 (usually skip C1 bump & C3) |
+| Git release only | C3 |
+
+Exact command names are **not** part of this spec.
+
+---
+
+## 7. Non-goals
+
+- Mandating Python/Node/Go/Make/etc.
+- Mandating a `tools/` directory layout.
+- Replacing product CI; this spec may be implemented as CI, local scripts, or both.
+- Defining app platforms, scaffolds, or agent skills.
+
+---
+
+## 8. Implementation notes for agents
+
+When asked to implement this file:
+
+1. Read §0 values; if empty, ask the user for I1–I13 before coding.
+2. Choose toolchain from the user’s language request + existing repo norms.
+3. Implement C1→C2→C3 against the IDs above; keep secrets out of the repo.
+4. Add a short “Implemented by” note under §9 (paths to scripts/workflows only).
+
+---
+
+## 9. Implemented by (fill after coding)
+
+| Capability | Entry / path |
+|------------|----------------|
+| C1 Version | `<…>` |
+| C2 Deploy | `<…>` |
+| C3 Git release | `<…>` |
+| Secrets example | `<…>` |

yjcli-0.0.3/src/yjcli/services/sync.py

@@ -0,0 +1,68 @@
+"""Sync agent docs / skills / rules into a target repo."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from yjcli.modules import paths
+from yjcli.modules.fsutil import copy_file, copy_tree, ensure_real_dir
+from yjcli.modules.prompt import abort
+
+
+def sync_agents(root: Path) -> None:
+    """Overwrite CLAUDE.md from AGENTS.md (AGENTS.md is the source of truth)."""
+    agents = root / "AGENTS.md"
+    claude = root / "CLAUDE.md"
+    if not agents.is_file():
+        abort(f"missing {agents} (edit AGENTS.md first)")
+    copy_file(agents, claude, force=True)
+    typer.echo("synced: AGENTS.md -> CLAUDE.md")
+
+
+def sync_skills(root: Path, *, force: bool = True) -> None:
+    """Copy packaged skills into .cursor/skills and .claude/skills."""
+    cursor_skills = root / ".cursor" / "skills"
+    claude_skills = root / ".claude" / "skills"
+    ensure_real_dir(cursor_skills)
+    ensure_real_dir(claude_skills)
+
+    skills_root = paths.skills_dir()
+    if not skills_root.is_dir():
+        abort(f"missing packaged skills: {skills_root}")
+
+    for skill_dir in sorted(p for p in skills_root.iterdir() if p.is_dir()):
+        name = skill_dir.name
+        copy_tree(skill_dir, cursor_skills / name, force=force)
+        copy_tree(skill_dir, claude_skills / name, force=force)
+    typer.echo("synced: packaged skills -> .cursor/skills, .claude/skills")
+
+
+def sync_rules(root: Path, *, force: bool = True) -> None:
+    """Copy packaged rules into .cursor/rules and .claude/rules."""
+    cursor_rules = root / ".cursor" / "rules"
+    claude_rules = root / ".claude" / "rules"
+    ensure_real_dir(cursor_rules)
+    ensure_real_dir(claude_rules)
+
+    cursor_src = paths.cursor_rules_dir()
+    claude_src = paths.claude_rules_dir()
+    if not cursor_src.is_dir() and not claude_src.is_dir():
+        abort("missing packaged cursor/claude rules")
+
+    for rule_file in sorted(cursor_src.glob("*")):
+        if rule_file.is_file():
+            copy_file(rule_file, cursor_rules / rule_file.name, force=force)
+
+    for rule_file in sorted(claude_src.glob("*")):
+        if rule_file.is_file():
+            copy_file(rule_file, claude_rules / rule_file.name, force=force)
+    typer.echo("synced: packaged rules -> .cursor/rules, .claude/rules")
+
+
+def sync_all(root: Path, *, force: bool = True) -> None:
+    """Sync AGENTS.md mirror, skills, and rules in one shot."""
+    sync_agents(root)
+    sync_skills(root, force=force)
+    sync_rules(root, force=force)

yjcli-0.0.3/src/yjcli/services/wiring.py

@@ -0,0 +1,42 @@
+"""Copy packaged Cursor/Claude skills & rules into a target repo."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from yjcli.modules import paths
+from yjcli.modules.fsutil import copy_file
+from yjcli.services import sync as sync_svc
+
+
+def ensure_agent_wiring(root: Path, *, force: bool = False) -> None:
+    """Install AGENTS docs, skills, rules, and Claude settings; mirror CLAUDE.md."""
+    templates = paths.templates_dir()
+    agents_src = templates / "AGENTS.md"
+    settings_src = templates / "settings.json"
+    if not agents_src.is_file():
+        raise FileNotFoundError(f"missing template: {agents_src}")
+    if not settings_src.is_file():
+        raise FileNotFoundError(f"missing template: {settings_src}")
+
+    copy_file(agents_src, root / "AGENTS.md", force=force)
+    # CLAUDE.md is always a mechanical mirror of AGENTS.md (never edited by hand).
+    if (root / "AGENTS.md").is_file():
+        sync_svc.sync_agents(root)
+
+    sync_svc.sync_skills(root, force=force)
+    sync_svc.sync_rules(root, force=force)
+    copy_file(settings_src, root / ".claude" / "settings.json", force=force)
+
+
+def ensure_root_from_templates(root: Path, *, force: bool = False) -> None:
+    """Copy root Makefile / TOOLS.md / .gitignore / make.bat from packaged templates."""
+    templates = paths.templates_dir()
+    for name in (".gitignore", "Makefile", "make.bat", "TOOLS.md"):
+        src = templates / name
+        if not src.is_file():
+            typer.echo(f"warn: missing template: {src}", err=True)
+            continue
+        copy_file(src, root / name, force=force)

yjcli-0.0.2/src/yjcli/services/wiring.py

@@ -1,61 +0,0 @@
-"""Copy packaged Cursor/Claude skills & rules into a target repo."""
-
-from __future__ import annotations
-
-from pathlib import Path
-
-import typer
-
-from yjcli.modules import paths
-from yjcli.modules.fsutil import copy_file, copy_tree, ensure_real_dir
-
-
-def ensure_agent_wiring(root: Path, *, force: bool = False) -> None:
-    """Install AGENTS/CLAUDE docs, skills, rules, and Claude settings."""
-    templates = paths.templates_dir()
-    agents_src = templates / "AGENTS.md"
-    settings_src = templates / "settings.json"
-    if not agents_src.is_file():
-        raise FileNotFoundError(f"missing template: {agents_src}")
-    if not settings_src.is_file():
-        raise FileNotFoundError(f"missing template: {settings_src}")
-
-    copy_file(agents_src, root / "AGENTS.md", force=force)
-    copy_file(agents_src, root / "CLAUDE.md", force=force)
-
-    cursor_skills = root / ".cursor" / "skills"
-    claude_skills = root / ".claude" / "skills"
-    cursor_rules = root / ".cursor" / "rules"
-    claude_rules = root / ".claude" / "rules"
-    ensure_real_dir(cursor_skills)
-    ensure_real_dir(claude_skills)
-    ensure_real_dir(cursor_rules)
-    ensure_real_dir(claude_rules)
-
-    skills_root = paths.skills_dir()
-    if skills_root.is_dir():
-        for skill_dir in sorted(p for p in skills_root.iterdir() if p.is_dir()):
-            name = skill_dir.name
-            copy_tree(skill_dir, cursor_skills / name, force=force)
-            copy_tree(skill_dir, claude_skills / name, force=force)
-
-    for rule_file in sorted(paths.cursor_rules_dir().glob("*")):
-        if rule_file.is_file():
-            copy_file(rule_file, cursor_rules / rule_file.name, force=force)
-
-    for rule_file in sorted(paths.claude_rules_dir().glob("*")):
-        if rule_file.is_file():
-            copy_file(rule_file, claude_rules / rule_file.name, force=force)
-
-    copy_file(settings_src, root / ".claude" / "settings.json", force=force)
-
-
-def ensure_root_from_templates(root: Path, *, force: bool = False) -> None:
-    """Copy root Makefile / .gitignore / make.bat from packaged templates."""
-    templates = paths.templates_dir()
-    for name in (".gitignore", "Makefile", "make.bat"):
-        src = templates / name
-        if not src.is_file():
-            typer.echo(f"warn: missing template: {src}", err=True)
-            continue
-        copy_file(src, root / name, force=force)