yjcli 0.2.5__tar.gz → 0.3.1__tar.gz

{yjcli-0.2.5 → yjcli-0.3.1}/.gitignore

@@ -4,8 +4,6 @@ venv/
 .env/
 .env.*
 !.env.examples
-# Packaged scaffold templates must ship env samples (still ignored in user repos).
-!src/yjcli/data/templates/**/.env.*
 
 # Python
 __pycache__/
@@ -38,3 +36,6 @@ Thumbs.db
 # Local tooling
 *.log
 .cache/
+
+# E2E sandbox (scripts/e2e.sh)
+sandbox/

yjcli-0.3.1/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.5
+Name: yjcli
+Version: 0.3.1
+Summary: Wizard that scaffolds YJ architecture repos: platforms, services, tooling plugins, and AI agent wiring (Cursor/Claude/Codex).
+Project-URL: Homepage, https://github.com/yseiren87/yjcli
+Project-URL: Repository, https://github.com/yseiren87/yjcli
+Project-URL: Issues, https://github.com/yseiren87/yjcli/issues
+Author: yseiren87
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,claude,cli,codex,cursor,scaffold
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Utilities
+Requires-Python: >=3.12
+Requires-Dist: questionary>=2.1.1
+Requires-Dist: rich>=15.0.0
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# yjcli
+
+Wizard that scaffolds YJ-architecture repositories: platform code folders,
+services, tooling plugins, and AI agent wiring (Cursor, Claude Code, Codex).
+
+Run `yjcli` with no arguments and it walks you through a checklist. Nothing is
+written until you confirm the plan at the end. Every step can also be answered
+with a command-line argument, which skips that step.
+
+## Install
+
+```bash
+uv tool install yjcli
+yjcli --version
+uv tool upgrade yjcli
+```
+
+## Quick start
+
+```bash
+cd /path/to/your-repo
+yjcli                                   # interactive wizard
+```
+
+```text
+  ✔ 1. LLM 대상     Cursor, Claude Code
+  ✔ 2. 플랫폼       backend, frontend
+  ✔ 3. 플러그인     runner, secrets
+  ▸ 4. 서비스 이름  (1/2) backend
+  ○ 5. 확인 및 실행
+
+? backend 서비스 이름 (공백 또는 , 로 구분): a1, a2
+  → backend/a1, backend/a2
+```
+
+The same thing without prompts:
+
+```bash
+yjcli -l cursor,claude -n backend=a1,a2 -n frontend=f1 --plugin runner,secrets -y
+```
+
+## Steps
+
+| # | Step | Argument | Notes |
+|---|------|----------|-------|
+| 1 | LLM targets | `-l/--llm cursor,claude,codex` · `all` | Multi-select (space toggles `[x]`) |
+| 2 | Platforms | `-p/--platform …` · `all` | Multi-select |
+| 3 | Plugins | `--plugin runner,secrets,builder` · `all` · `none` | Required plugins are added automatically |
+| 4 | Service names | `-n/--name <platform>=a1,a2` (repeatable) | One screen per platform; split names with spaces or commas. `-n` alone also selects the platform |
+| — | Platform options | `-o/--option backend=proto` | Asked right after the names of a new platform |
+| 5 | Confirm | `-y/--yes` · `--dry-run` | Non-interactive runs need `--yes` or `--dry-run` |
+
+`←` goes back one screen. Skills are not asked for — they follow the platforms.
+
+## Platforms
+
+Platforms hold **code only**: service folders, stack files and `.env.examples`.
+
+| Platform | What | Skill |
+|----------|------|-------|
+| `backend` | single backend (API); optional `proto` | `yj-backend` |
+| `backend-msa` | gRPC microservices; `proto/` always | `yj-backend-msa` |
+| `backend-ssr` | server-rendered backend; `views/` always; optional `proto` | `yj-backend-ssr` |
+| `frontend` | Vite + React + TS | `yj-frontend` |
+| `mobile-app` | Flutter | `yj-mobile-app` |
+| `pc-app` | Electron | `yj-pc-app` |
+| `cli` | CLI apps | `yj-cli` |
+| `browser-extension` | MV3; `native_*` services are native hosts | `yj-browser-extension` + `yj-backend` |
+| `scheduler` | periodic batch jobs | `yj-scheduler` |
+
+## Plugins (repository tooling under `tools/`)
+
+| Plugin | Installs | Requires |
+|--------|----------|----------|
+| `runner` | `tools/runner/run.{sh,bat,ps1}`, root `Makefile` / `make.bat` → `make <platform> [NAME=<service>]` | `secrets` |
+| `secrets` | `tools/secrets/<platform>/<service>/.env.{local-dev,development,production}` — **committed in plain text** (private repos only) | — |
+| `builder` | `tools/builder/` (build/deploy hosts, `steps/{proto,ssr,docker}.sh`, per-platform stubs), `Dockerfile` for deployable services → `make <platform>-build-<env>` / `-deploy-<env>` | `secrets` |
+
+Each service declares its local command as `RUN_COMMAND` in
+`tools/secrets/<platform>/<service>/.env.local-dev`; the runner exports that file
+and runs it. Generated build/deploy stubs fail with an implementation prompt
+until you replace them.
+
+## Updating
+
+### Pick up a new yjcli release
+
+When skills, AGENTS.md rules or managed scripts change in yjcli:
+
+```bash
+uv tool upgrade yjcli
+yjcli status            # tells you a newer yjcli is installed
+yjcli update --diff     # review what changes, then confirm (or -y)
+```
+
+`yjcli update` keeps your selection and only re-renders what yjcli owns. A yjcli
+that is **older** than the one that last wrote `.yjcli/manifest.toml` refuses to
+run (so teammates on old versions cannot roll files back); `--force` overrides.
+
+### Change the selection
+
+```bash
+yjcli                                      # wizard, stored selection as defaults
+yjcli --plugin runner,secrets,builder -y   # add the builder plugin
+yjcli service add -n backend=a3            # add services
+yjcli plan --diff                          # show the plan only
+```
+
+### What yjcli owns vs. what you own
+
+| File kind | On update |
+|-----------|-----------|
+| managed (skills, `CLAUDE.md`, `tools/runner/*`, `Makefile`, builder hosts/steps) | refreshed; skipped with a warning if you edited it (`--force` overwrites) |
+| blocks (`AGENTS.md` `<!-- yjcli:rules/skills/layout -->`, `.gitignore` `# >>> yjcli:managed`) | only the block is regenerated; everything outside is yours |
+| seed (`AGENTS.md` body, env files, build/deploy stubs, `Dockerfile`, settings) | created once when its owner is new; yours afterwards |
+
+Customize a skill without losing updates: write the extra rules in
+`.yjcli/skills/<skill>.md` (e.g. `.yjcli/skills/yj-backend.md`). yjcli appends
+them to that skill for every LLM on each render. Put project-wide agent rules
+under `### Project rules` in AGENTS.md (outside the blocks).
+
+yjcli never deletes services or files you own. Removing a plugin or LLM deletes
+only its managed files; your own skills in the skills folders are left alone.
+
+## Development
+
+```bash
+uv sync
+uv run python -m unittest discover -s tests   # unit tests
+scripts/e2e.sh                                 # end-to-end scenarios into ./sandbox
+scripts/e2e.sh -k wizard -v                    # one case, with output on failure
+```
+
+## Releasing (maintainers)
+
+```bash
+./release.sh                  # bump → tests → build + PyPI dry-run → commit/tag/push → publish
+./release.sh --publish-only   # publish an already pushed release/X.Y.Z tag
+```
+
+Every step waits for `y` or `exit` (case-insensitive). Uncommitted changes do
+not block: they are listed in step 1 and committed together with the version
+bump in step 5, where you type the commit message. The bump step asks for
+`major`, `minor` or `fix` (no default) and bumps the `pyproject.toml` version,
+which always equals the last release (only `release.sh` changes it).
+Tags follow `release/X.Y.Z`. Tokens go in `.env.release` (git-ignored):
+
+```bash
+UV_PUBLISH_TOKEN=pypi-...       # required
+GITHUB_TOKEN=github_pat_...     # optional, used only for git push
+```
+
+Design notes: [`docs/redesign.md`](docs/redesign.md).

yjcli-0.3.1/README.md

@@ -0,0 +1,153 @@
+# yjcli
+
+Wizard that scaffolds YJ-architecture repositories: platform code folders,
+services, tooling plugins, and AI agent wiring (Cursor, Claude Code, Codex).
+
+Run `yjcli` with no arguments and it walks you through a checklist. Nothing is
+written until you confirm the plan at the end. Every step can also be answered
+with a command-line argument, which skips that step.
+
+## Install
+
+```bash
+uv tool install yjcli
+yjcli --version
+uv tool upgrade yjcli
+```
+
+## Quick start
+
+```bash
+cd /path/to/your-repo
+yjcli                                   # interactive wizard
+```
+
+```text
+  ✔ 1. LLM 대상     Cursor, Claude Code
+  ✔ 2. 플랫폼       backend, frontend
+  ✔ 3. 플러그인     runner, secrets
+  ▸ 4. 서비스 이름  (1/2) backend
+  ○ 5. 확인 및 실행
+
+? backend 서비스 이름 (공백 또는 , 로 구분): a1, a2
+  → backend/a1, backend/a2
+```
+
+The same thing without prompts:
+
+```bash
+yjcli -l cursor,claude -n backend=a1,a2 -n frontend=f1 --plugin runner,secrets -y
+```
+
+## Steps
+
+| # | Step | Argument | Notes |
+|---|------|----------|-------|
+| 1 | LLM targets | `-l/--llm cursor,claude,codex` · `all` | Multi-select (space toggles `[x]`) |
+| 2 | Platforms | `-p/--platform …` · `all` | Multi-select |
+| 3 | Plugins | `--plugin runner,secrets,builder` · `all` · `none` | Required plugins are added automatically |
+| 4 | Service names | `-n/--name <platform>=a1,a2` (repeatable) | One screen per platform; split names with spaces or commas. `-n` alone also selects the platform |
+| — | Platform options | `-o/--option backend=proto` | Asked right after the names of a new platform |
+| 5 | Confirm | `-y/--yes` · `--dry-run` | Non-interactive runs need `--yes` or `--dry-run` |
+
+`←` goes back one screen. Skills are not asked for — they follow the platforms.
+
+## Platforms
+
+Platforms hold **code only**: service folders, stack files and `.env.examples`.
+
+| Platform | What | Skill |
+|----------|------|-------|
+| `backend` | single backend (API); optional `proto` | `yj-backend` |
+| `backend-msa` | gRPC microservices; `proto/` always | `yj-backend-msa` |
+| `backend-ssr` | server-rendered backend; `views/` always; optional `proto` | `yj-backend-ssr` |
+| `frontend` | Vite + React + TS | `yj-frontend` |
+| `mobile-app` | Flutter | `yj-mobile-app` |
+| `pc-app` | Electron | `yj-pc-app` |
+| `cli` | CLI apps | `yj-cli` |
+| `browser-extension` | MV3; `native_*` services are native hosts | `yj-browser-extension` + `yj-backend` |
+| `scheduler` | periodic batch jobs | `yj-scheduler` |
+
+## Plugins (repository tooling under `tools/`)
+
+| Plugin | Installs | Requires |
+|--------|----------|----------|
+| `runner` | `tools/runner/run.{sh,bat,ps1}`, root `Makefile` / `make.bat` → `make <platform> [NAME=<service>]` | `secrets` |
+| `secrets` | `tools/secrets/<platform>/<service>/.env.{local-dev,development,production}` — **committed in plain text** (private repos only) | — |
+| `builder` | `tools/builder/` (build/deploy hosts, `steps/{proto,ssr,docker}.sh`, per-platform stubs), `Dockerfile` for deployable services → `make <platform>-build-<env>` / `-deploy-<env>` | `secrets` |
+
+Each service declares its local command as `RUN_COMMAND` in
+`tools/secrets/<platform>/<service>/.env.local-dev`; the runner exports that file
+and runs it. Generated build/deploy stubs fail with an implementation prompt
+until you replace them.
+
+## Updating
+
+### Pick up a new yjcli release
+
+When skills, AGENTS.md rules or managed scripts change in yjcli:
+
+```bash
+uv tool upgrade yjcli
+yjcli status            # tells you a newer yjcli is installed
+yjcli update --diff     # review what changes, then confirm (or -y)
+```
+
+`yjcli update` keeps your selection and only re-renders what yjcli owns. A yjcli
+that is **older** than the one that last wrote `.yjcli/manifest.toml` refuses to
+run (so teammates on old versions cannot roll files back); `--force` overrides.
+
+### Change the selection
+
+```bash
+yjcli                                      # wizard, stored selection as defaults
+yjcli --plugin runner,secrets,builder -y   # add the builder plugin
+yjcli service add -n backend=a3            # add services
+yjcli plan --diff                          # show the plan only
+```
+
+### What yjcli owns vs. what you own
+
+| File kind | On update |
+|-----------|-----------|
+| managed (skills, `CLAUDE.md`, `tools/runner/*`, `Makefile`, builder hosts/steps) | refreshed; skipped with a warning if you edited it (`--force` overwrites) |
+| blocks (`AGENTS.md` `<!-- yjcli:rules/skills/layout -->`, `.gitignore` `# >>> yjcli:managed`) | only the block is regenerated; everything outside is yours |
+| seed (`AGENTS.md` body, env files, build/deploy stubs, `Dockerfile`, settings) | created once when its owner is new; yours afterwards |
+
+Customize a skill without losing updates: write the extra rules in
+`.yjcli/skills/<skill>.md` (e.g. `.yjcli/skills/yj-backend.md`). yjcli appends
+them to that skill for every LLM on each render. Put project-wide agent rules
+under `### Project rules` in AGENTS.md (outside the blocks).
+
+yjcli never deletes services or files you own. Removing a plugin or LLM deletes
+only its managed files; your own skills in the skills folders are left alone.
+
+## Development
+
+```bash
+uv sync
+uv run python -m unittest discover -s tests   # unit tests
+scripts/e2e.sh                                 # end-to-end scenarios into ./sandbox
+scripts/e2e.sh -k wizard -v                    # one case, with output on failure
+```
+
+## Releasing (maintainers)
+
+```bash
+./release.sh                  # bump → tests → build + PyPI dry-run → commit/tag/push → publish
+./release.sh --publish-only   # publish an already pushed release/X.Y.Z tag
+```
+
+Every step waits for `y` or `exit` (case-insensitive). Uncommitted changes do
+not block: they are listed in step 1 and committed together with the version
+bump in step 5, where you type the commit message. The bump step asks for
+`major`, `minor` or `fix` (no default) and bumps the `pyproject.toml` version,
+which always equals the last release (only `release.sh` changes it).
+Tags follow `release/X.Y.Z`. Tokens go in `.env.release` (git-ignored):
+
+```bash
+UV_PUBLISH_TOKEN=pypi-...       # required
+GITHUB_TOKEN=github_pat_...     # optional, used only for git push
+```
+
+Design notes: [`docs/redesign.md`](docs/redesign.md).

{yjcli-0.2.5 → yjcli-0.3.1}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "yjcli"
-version = "0.2.5"
-description = "Scaffold platforms, services, and AI agent wiring (Cursor/Claude/Codex) for YJ architecture repos."
+version = "0.3.1"
+description = "Wizard that scaffolds YJ architecture repos: platforms, services, tooling plugins, and AI agent wiring (Cursor/Claude/Codex)."
 readme = "README.md"
 requires-python = ">=3.12"
 license = "MIT"
@@ -22,6 +22,8 @@ classifiers = [
   "Topic :: Utilities",
 ]
 dependencies = [
+  "questionary>=2.1.1",
+  "rich>=15.0.0",
   "typer>=0.12",
 ]
 

yjcli-0.3.1/src/yjcli/catalog/__init__.py

@@ -0,0 +1,14 @@
+"""Declarative catalog: LLM adapters, platforms, plugins, skills.
+
+Everything the user can pick (and everything derived from a pick) is data here.
+Planner logic reads the catalog; it never branches on a platform/plugin name.
+"""
+
+from __future__ import annotations
+
+from importlib.resources import files
+from pathlib import Path
+
+
+def data_root() -> Path:
+    return Path(str(files("yjcli.data")))

yjcli-0.3.1/src/yjcli/catalog/llms.py

@@ -0,0 +1,38 @@
+"""LLM adapters: instruction file + skills directory + extra settings."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class Extra:
+    """A seed file the adapter installs once (template path under data/templates)."""
+
+    template: str
+    dest: str
+
+
+@dataclass(frozen=True)
+class LLM:
+    id: str
+    label: str
+    skills_dir: str
+    # File that imports AGENTS.md (None when the tool reads AGENTS.md directly).
+    instructions: str | None = None
+    extras: tuple[Extra, ...] = field(default_factory=tuple)
+
+
+LLMS: tuple[LLM, ...] = (
+    LLM(id="cursor", label="Cursor", skills_dir=".cursor/skills"),
+    LLM(
+        id="claude",
+        label="Claude Code",
+        skills_dir=".claude/skills",
+        instructions="CLAUDE.md",
+        extras=(Extra("root/claude-settings.json", ".claude/settings.json"),),
+    ),
+    LLM(id="codex", label="Codex", skills_dir=".agents/skills"),
+)
+
+LLM_BY_ID: dict[str, LLM] = {llm.id: llm for llm in LLMS}

yjcli-0.3.1/src/yjcli/catalog/platforms.py

@@ -0,0 +1,163 @@
+"""Platforms: code-only scaffolds (service folders, stack files, .env.examples)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class Option:
+    """Platform-level code option, asked once when the platform is created.
+
+    Whether it is "on" later is decided by disk state (the created folder), not
+    by the manifest — yjcli only creates the starting files and never deletes them.
+    """
+
+    id: str
+    label: str
+    creates: tuple[str, ...]  # paths relative to the platform root
+    default: bool = False
+    fixed: bool = False  # always applied, never asked
+
+
+@dataclass(frozen=True)
+class ServiceVariant:
+    """Alternative service shape selected by name prefix (e.g. native_*)."""
+
+    prefix: str
+    env_kind: str
+    service_dirs: tuple[str, ...]
+    files: tuple[tuple[str, str], ...] = ()  # (dest, content)
+
+
+@dataclass(frozen=True)
+class Platform:
+    id: str
+    hint: str
+    role: str  # English role text for the AGENTS.md layout table
+    skills: tuple[str, ...]
+    env_kind: str  # listen | worker | app
+    service_dirs: tuple[str, ...]
+    env_vars: dict[str, str] = field(default_factory=dict)
+    stack_template: str | None = None  # dir under data/templates/platform
+    service_files: tuple[tuple[str, str], ...] = ()  # (dest, content)
+    options: tuple[Option, ...] = ()
+    variants: tuple[ServiceVariant, ...] = ()
+    deployable: bool = False  # builder plugin stamps a Dockerfile into each service
+
+    def variant_for(self, service: str) -> ServiceVariant | None:
+        for variant in self.variants:
+            if service.startswith(variant.prefix):
+                return variant
+        return None
+
+
+_BACKEND_DIRS = ("apps", "services", "domains", "modules")
+
+_PROTO = Option(
+    id="proto",
+    label="gRPC/protobuf 사용 (proto/ 생성)",
+    creates=("proto/.gitkeep", "proto/dist/.gitkeep"),
+)
+
+PLATFORMS: tuple[Platform, ...] = (
+    Platform(
+        id="backend",
+        hint="단일 백엔드 (API)",
+        role="Single backend services (API)",
+        skills=("yj-backend",),
+        env_kind="listen",
+        env_vars={"__PORT__": "8080"},
+        service_dirs=_BACKEND_DIRS,
+        options=(_PROTO,),
+        deployable=True,
+    ),
+    Platform(
+        id="backend-msa",
+        hint="gRPC MSA",
+        role="gRPC microservices sharing one proto contract",
+        skills=("yj-backend-msa",),
+        env_kind="listen",
+        env_vars={"__PORT__": "8080"},
+        service_dirs=_BACKEND_DIRS,
+        options=(Option(id="proto", label=_PROTO.label, creates=_PROTO.creates, fixed=True),),
+        deployable=True,
+    ),
+    Platform(
+        id="backend-ssr",
+        hint="서버 템플릿/SSR",
+        role="Server-rendered (SSR/MPA) backend services",
+        skills=("yj-backend-ssr",),
+        env_kind="listen",
+        env_vars={"__PORT__": "8080"},
+        service_dirs=(*_BACKEND_DIRS, "views"),
+        options=(_PROTO,),
+        deployable=True,
+    ),
+    Platform(
+        id="frontend",
+        hint="Vite + React + TS",
+        role="Vite + React + TS web apps",
+        skills=("yj-frontend",),
+        env_kind="listen",
+        env_vars={"__PORT__": "5173"},
+        service_dirs=("src",),
+        stack_template="frontend",
+        deployable=True,
+    ),
+    Platform(
+        id="mobile-app",
+        hint="Flutter",
+        role="Flutter mobile apps",
+        skills=("yj-mobile-app",),
+        env_kind="app",
+        service_dirs=("lib",),
+    ),
+    Platform(
+        id="pc-app",
+        hint="Electron",
+        role="Electron desktop apps",
+        skills=("yj-pc-app",),
+        env_kind="app",
+        service_dirs=("main", "preload", "renderer/src"),
+    ),
+    Platform(
+        id="cli",
+        hint="CLI",
+        role="Command-line applications",
+        skills=("yj-cli",),
+        env_kind="app",
+        service_dirs=("apps", "services", "modules"),
+    ),
+    Platform(
+        id="browser-extension",
+        hint="MV3",
+        role="MV3 browser extensions (`native_*` = native messaging hosts)",
+        skills=("yj-browser-extension", "yj-backend"),
+        env_kind="app",
+        service_dirs=("src/background", "src/content", "src/popup", "src/lib"),
+        service_files=(("manifest.json", "{}\n"),),
+        variants=(
+            ServiceVariant(
+                prefix="native_",
+                env_kind="worker",
+                service_dirs=("apps", "services", "modules"),
+            ),
+        ),
+    ),
+    Platform(
+        id="scheduler",
+        hint="주기 배치 작업",
+        role="Long-running schedulers for periodic batch jobs",
+        skills=("yj-scheduler",),
+        env_kind="worker",
+        service_dirs=_BACKEND_DIRS,
+        deployable=True,
+    ),
+)
+
+PLATFORM_BY_ID: dict[str, Platform] = {p.id: p for p in PLATFORMS}
+
+# Folder names under a platform root that are not services.
+NON_SERVICE_DIRS: frozenset[str] = frozenset({"proto"})
+RESERVED_SERVICE_NAMES: frozenset[str] = NON_SERVICE_DIRS