yjcli 0.2.4__tar.gz → 0.2.5__tar.gz

{yjcli-0.2.4 → yjcli-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: yjcli
-Version: 0.2.4
+Version: 0.2.5
 Summary: Scaffold platforms, services, and AI agent wiring (Cursor/Claude/Codex) for YJ architecture repos.
 Project-URL: Homepage, https://github.com/yseiren87/yjcli
 Project-URL: Repository, https://github.com/yseiren87/yjcli
@@ -77,13 +77,59 @@ Use with `-t` / `--type` (repeatable on `init` / `platform add`):
 - Claude `settings.json`
 - Root `Makefile`, `make.bat`, `TOOLS.md`, `.gitignore`
 - `Diff.md` — user-maintained architecture difference and manual restoration notes
-- Selected platform roots with `scripts/run.*` and development/production deploy templates
+- Selected platform roots with `scripts/run.*` and development/production build/deploy templates
 
-The root `Makefile` / `make.bat` wires platform run and deploy entry points. Deploy
-templates print the exact file to implement and fail until the project supplies
-its build/package and upload logic. They remain platform-level; do not add
+The root `Makefile` / `make.bat` wires platform run, build, and deploy entry points.
+Build/deploy templates print the exact file to implement and fail until the project
+supplies its build/package and upload logic. They remain platform-level; do not add
 per-service `scripts/` directories or per-service Makefiles.
 
+`run.*` ships as `.sh` + `.bat` + `.ps1` since local dev runs natively per platform.
+`build-*` and `deploy-*` ship as `.sh` only — build/deploy tooling (Docker, etc.) is
+not native to Windows, so `make.bat` runs those targets through WSL; macOS/Linux use
+the shell script directly.
+
+`build-common.sh` is the same file for every platform and is a thin plugin host:
+it runs every `scripts/plugin-build-*.sh` file present, then falls through to its
+own generic build guard. The `build` segment names the consumer (a deploy-side
+plugin would be `plugin-deploy-*.sh` instead). Each plugin is its own file —
+visible in `scripts/`, and runnable standalone — and self-detects whether it
+applies by folder presence, not a platform-name check, so any platform can opt in.
+
+- `plugin-build-proto.sh` → protoc codegen guard when `<platform>/proto/` exists.
+  `backend` always has this (fixed gRPC MSA root, see `yj-backend-msa`); any other
+  platform (including `backend-service`) gets the same guard only if it creates
+  `proto/` too. protoc is the standard; buf is not used.
+- `plugin-build-ssr.sh` → template/asset build guard when
+  `<platform>/{service}/views/` exists, checked per service. Any platform's
+  service can opt in by creating `views/`.
+- `plugin-build-docker.sh` → docker image **build only** (no push, no
+  swarm/stack rollout — that belongs in a deploy-side plugin) guard, per
+  service that has a `Dockerfile` (delete it to opt that service out). Builds
+  always use `.env.development` or `.env.production` depending on which
+  environment is targeted. The image version comes from the service's
+  `package.json`/`pyproject.toml` `version` field when present, otherwise the
+  `VERSION` env var — set it for languages with no package-manifest version
+  field.
+
+None of these plugins imply each other, and using gRPC in `backend-service` does
+not make it MSA — see `yj-backend-msa` / `yj-backend-service` for what each
+option chapter actually changes.
+
+- `yjcli service add` adds `Dockerfile` + `.dockerignore` to new services under
+  deployable platforms (`backend`, `backend-service`, `frontend`, `scheduler`);
+  `cli`/`mobile-app`/`pc-app`/`browser-extension` are local/client artifacts, not
+  docker-swarm services, so they don't get one. The Dockerfile is
+  language-agnostic and intentionally has no `FROM` yet — `docker build` fails
+  until it's replaced, matching every other generated build/deploy stub.
+
+`deploy-common.sh` is the same kind of plugin host for the deploy side: after
+calling the matching build script, it runs every `scripts/plugin-deploy-*.sh`
+file present (none ship by default — pushing an image, `docker stack deploy`,
+`kubectl apply`, etc. are deploy-side plugins the project adds). `deploy-development.sh`
+/ `deploy-production.sh` call `deploy-common.sh` and then own their own
+upload/rollout guidance only.
+
 `Diff.md` is created only when missing, including with `init --force`. yjcli never
 reads, updates, overwrites, or uses it for automatic restoration during sync or
 migration.
@@ -105,8 +151,10 @@ inferring npm, uv, Go, or another language/runtime from project manifests.
 ```bash
 make <platform>                 # all services under that platform (concurrent)
 make <platform> NAME=<service>  # one service
+make <platform>-build-development  [NAME=<service>]
+make <platform>-build-production   [NAME=<service>]
 make <platform>-deploy-development [NAME=<service>]
-make <platform>-deploy-production [NAME=<service>]
+make <platform>-deploy-production  [NAME=<service>]
 make help
 ```
 
@@ -116,7 +164,7 @@ make help
 |---------|------|
 | `yjcli sync agents` | After editing `AGENTS.md` — refreshes `CLAUDE.md` |
 | `yjcli sync skills` | Refresh packaged skills (Cursor / Claude / Codex) |
-| `yjcli sync make` | Overwrite root make/run files; install missing deploy scripts while preserving implemented ones |
+| `yjcli sync make` | Overwrite root make/run files; install missing build/deploy scripts while preserving implemented ones |
 | `yjcli sync all` | Soft upgrade — mirror CLAUDE + skills + make (**keeps** your `AGENTS.md`) |
 | `yjcli sync migrate -y` | **Hard** upgrade — package template overwrites `AGENTS.md`, wipes skills dirs, drops legacy rules/`.agent`, refreshes settings/TOOLS/gitignore/make |
 

{yjcli-0.2.4 → yjcli-0.2.5}/README.md

@@ -52,13 +52,59 @@ Use with `-t` / `--type` (repeatable on `init` / `platform add`):
 - Claude `settings.json`
 - Root `Makefile`, `make.bat`, `TOOLS.md`, `.gitignore`
 - `Diff.md` — user-maintained architecture difference and manual restoration notes
-- Selected platform roots with `scripts/run.*` and development/production deploy templates
+- Selected platform roots with `scripts/run.*` and development/production build/deploy templates
 
-The root `Makefile` / `make.bat` wires platform run and deploy entry points. Deploy
-templates print the exact file to implement and fail until the project supplies
-its build/package and upload logic. They remain platform-level; do not add
+The root `Makefile` / `make.bat` wires platform run, build, and deploy entry points.
+Build/deploy templates print the exact file to implement and fail until the project
+supplies its build/package and upload logic. They remain platform-level; do not add
 per-service `scripts/` directories or per-service Makefiles.
 
+`run.*` ships as `.sh` + `.bat` + `.ps1` since local dev runs natively per platform.
+`build-*` and `deploy-*` ship as `.sh` only — build/deploy tooling (Docker, etc.) is
+not native to Windows, so `make.bat` runs those targets through WSL; macOS/Linux use
+the shell script directly.
+
+`build-common.sh` is the same file for every platform and is a thin plugin host:
+it runs every `scripts/plugin-build-*.sh` file present, then falls through to its
+own generic build guard. The `build` segment names the consumer (a deploy-side
+plugin would be `plugin-deploy-*.sh` instead). Each plugin is its own file —
+visible in `scripts/`, and runnable standalone — and self-detects whether it
+applies by folder presence, not a platform-name check, so any platform can opt in.
+
+- `plugin-build-proto.sh` → protoc codegen guard when `<platform>/proto/` exists.
+  `backend` always has this (fixed gRPC MSA root, see `yj-backend-msa`); any other
+  platform (including `backend-service`) gets the same guard only if it creates
+  `proto/` too. protoc is the standard; buf is not used.
+- `plugin-build-ssr.sh` → template/asset build guard when
+  `<platform>/{service}/views/` exists, checked per service. Any platform's
+  service can opt in by creating `views/`.
+- `plugin-build-docker.sh` → docker image **build only** (no push, no
+  swarm/stack rollout — that belongs in a deploy-side plugin) guard, per
+  service that has a `Dockerfile` (delete it to opt that service out). Builds
+  always use `.env.development` or `.env.production` depending on which
+  environment is targeted. The image version comes from the service's
+  `package.json`/`pyproject.toml` `version` field when present, otherwise the
+  `VERSION` env var — set it for languages with no package-manifest version
+  field.
+
+None of these plugins imply each other, and using gRPC in `backend-service` does
+not make it MSA — see `yj-backend-msa` / `yj-backend-service` for what each
+option chapter actually changes.
+
+- `yjcli service add` adds `Dockerfile` + `.dockerignore` to new services under
+  deployable platforms (`backend`, `backend-service`, `frontend`, `scheduler`);
+  `cli`/`mobile-app`/`pc-app`/`browser-extension` are local/client artifacts, not
+  docker-swarm services, so they don't get one. The Dockerfile is
+  language-agnostic and intentionally has no `FROM` yet — `docker build` fails
+  until it's replaced, matching every other generated build/deploy stub.
+
+`deploy-common.sh` is the same kind of plugin host for the deploy side: after
+calling the matching build script, it runs every `scripts/plugin-deploy-*.sh`
+file present (none ship by default — pushing an image, `docker stack deploy`,
+`kubectl apply`, etc. are deploy-side plugins the project adds). `deploy-development.sh`
+/ `deploy-production.sh` call `deploy-common.sh` and then own their own
+upload/rollout guidance only.
+
 `Diff.md` is created only when missing, including with `init --force`. yjcli never
 reads, updates, overwrites, or uses it for automatic restoration during sync or
 migration.
@@ -80,8 +126,10 @@ inferring npm, uv, Go, or another language/runtime from project manifests.
 ```bash
 make <platform>                 # all services under that platform (concurrent)
 make <platform> NAME=<service>  # one service
+make <platform>-build-development  [NAME=<service>]
+make <platform>-build-production   [NAME=<service>]
 make <platform>-deploy-development [NAME=<service>]
-make <platform>-deploy-production [NAME=<service>]
+make <platform>-deploy-production  [NAME=<service>]
 make help
 ```
 
@@ -91,7 +139,7 @@ make help
 |---------|------|
 | `yjcli sync agents` | After editing `AGENTS.md` — refreshes `CLAUDE.md` |
 | `yjcli sync skills` | Refresh packaged skills (Cursor / Claude / Codex) |
-| `yjcli sync make` | Overwrite root make/run files; install missing deploy scripts while preserving implemented ones |
+| `yjcli sync make` | Overwrite root make/run files; install missing build/deploy scripts while preserving implemented ones |
 | `yjcli sync all` | Soft upgrade — mirror CLAUDE + skills + make (**keeps** your `AGENTS.md`) |
 | `yjcli sync migrate -y` | **Hard** upgrade — package template overwrites `AGENTS.md`, wipes skills dirs, drops legacy rules/`.agent`, refreshes settings/TOOLS/gitignore/make |
 

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

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

{yjcli-0.2.4 → yjcli-0.2.5}/src/yjcli/data/skills/yj-arch-core/SKILL.md

@@ -46,13 +46,59 @@ scheduler/            # yj-scheduler
   `install`, or `help` targets. Do not add per-service `scripts/`.
   Root `make <platform>` starts all services under that platform (concurrent); `NAME=<service>` runs one.
   Platforms run via `*/scripts/run.*`; services are sibling dirs created with `yjcli service add`.
-- The root `Makefile` / `make.bat` wires platform run and deploy commands. Use
+- The root `Makefile` / `make.bat` wires platform run, build, and deploy commands. Use
+  `<platform>-build-development|production [NAME=<service>]` for builds and
   `<platform>-deploy-development|production [NAME=<service>]` for deploys.
-  `deploy-common.*` owns shared build/package preparation; the environment-specific
-  deploy script calls it and then owns upload/rollout. Generated deploy scripts fail
-  with an implementation prompt until the repository replaces their guarded stubs.
-- Deploy scripts are repository-owned after creation. `yjcli sync make` installs
-  missing deploy scripts but preserves existing ones.
+  `build-common.sh` owns shared build/package preparation; the environment-specific
+  build script (`build-development.sh` / `build-production.sh`) calls it.
+  `deploy-common.sh` owns shared deploy orchestration (calls the matching build
+  script, then runs deploy plugins); the environment-specific deploy script
+  (`deploy-development.sh` / `deploy-production.sh`) calls it first and then
+  owns upload/rollout guidance only. Generated build/deploy scripts fail with an
+  implementation prompt until the repository replaces their guarded stubs.
+- `run.*` ships as `.sh` + `.bat` + `.ps1` (local dev runs natively per platform).
+  `build-*` and `deploy-*` are `.sh` only — build/deploy tooling is not native to
+  Windows, so `make.bat` runs those targets through WSL.
+- Build/deploy scripts are repository-owned after creation. `yjcli sync make` installs
+  missing build/deploy scripts but preserves existing ones.
+- `build-common.sh` is the same file for every platform — it is not backend-specific.
+  It is a thin plugin host: it runs every `scripts/plugin-build-*.sh` file present,
+  then falls through to its own generic build guard. Each capability is its own
+  file, self-detected by folder presence at runtime, not by branching on platform
+  name — so any platform can opt in. (A deploy-side plugin would be
+  `plugin-deploy-*.sh` — the naming segment names the consumer.)
+  - `plugin-build-proto.sh` → protoc codegen guard when `<platform>/proto/` exists
+    (schema `proto/*.proto` → generated `proto/dist/{lang}`). `backend` always has
+    this (fixed gRPC MSA root); any other platform gets the same guard only if it
+    creates a `proto/` folder too — do not assume gRPC on non-backend platforms.
+    protoc is the standard; buf is not used.
+  - `plugin-build-ssr.sh` → template/asset build guard when
+    `<platform>/{service}/views/` exists, checked per service (or across all
+    services when no service is targeted). Any platform's service may opt in by
+    creating `views/` — this is not backend-service-specific either.
+  - `plugin-build-docker.sh` → docker image **build only** guard (no push, no
+    swarm/stack rollout — that is a deploy-side plugin's job, not this one),
+    per service that has a `Dockerfile` (delete it to opt that service out).
+    Builds use `{service}/.env.development` or `.env.production` matching the
+    target environment. Image version: the service's `package.json` or
+    `pyproject.toml` `version` field when present, else the `VERSION` env var.
+  None of these plugins imply each other, and none imply MSA: a backend-service
+  using gRPC is still a single deployable, not multiple services sharing a
+  proto contract. Each plugin is also runnable standalone (e.g.
+  `./plugin-build-proto.sh development`) for testing without the base build guard.
+- `yjcli service add` adds `Dockerfile` + `.dockerignore` to new services under
+  deployable platforms (`backend`, `backend-service`, `frontend`, `scheduler`)
+  — not under `cli`/`mobile-app`/`pc-app`/`browser-extension`, which are
+  local/client artifacts, not docker-swarm services. The Dockerfile is
+  language-agnostic with no `FROM` yet — `docker build` fails until replaced,
+  same guard-until-implemented contract as the other stubs.
+- `deploy-common.sh` is the deploy-side plugin host, same contract as
+  `build-common.sh`: after calling the matching build script, it runs every
+  `scripts/plugin-deploy-*.sh` file present. None ship by default — a project
+  adds one (e.g. an image-push + `docker stack deploy` plugin, `kubectl apply`,
+  nginx/reverse-proxy) when it needs it. `deploy-development.sh` /
+  `deploy-production.sh` call `deploy-common.sh` and then own upload/rollout
+  guidance only.
 - `Diff.md` is an optional, user-maintained reference for meaningful architecture
   differences from yjcli defaults and their manual restoration notes. Update it
   when that record would help, but never treat it as an automated sync, migration,

{yjcli-0.2.4 → yjcli-0.2.5}/src/yjcli/data/skills/yj-backend-msa/SKILL.md

@@ -4,8 +4,10 @@ description: >-
   Backend MSA architecture with mandatory gRPC/protobuf. Use only when creating
   or editing code under backend/. Language-agnostic (Go/Python/Java/etc.).
   Covers backend/{service}, backend/proto, and proto/dist/{lang}. Supports owner,
-  policy, and edge/gateway services (domains optional). Do not use for
-  backend-service/, frontend/, mobile-app/, pc-app/, cli/, or browser-extension/.
+  policy, and edge/gateway services (domains optional). Optional server-templating
+  (SSR) add-on for a service that must render HTML, same as backend-service — not
+  a separate platform. Do not use for backend-service/, frontend/, mobile-app/,
+  pc-app/, cli/, or browser-extension/.
 ---
 
 # yj-backend-msa
@@ -52,6 +54,34 @@ Omit empty `domains/` trees. Do not invent fake repositories to “have a domain
 - Generated stubs go to `backend/proto/dist/{lang}/`.
 - Other platforms (e.g. `mobile-app`) may **symlink** to `backend/proto/dist/{lang}` — they must not own `.proto` copies.
 - Prefer package boundaries in proto that align with service boundaries.
+- Regeneration is wired through `backend/scripts/plugin-build-proto.sh` — a plugin
+  file every platform gets (not backend-specific), which auto-detects
+  `backend/proto/` and adds a protoc codegen guard (protoc is the standard here;
+  buf is not used). It runs automatically as part of `build-common.sh`, invoked via
+  `make backend-build-development|production`, and is also runnable standalone.
+  Implement codegen there, not as an ad-hoc one-off command.
+
+## Optional: server templating (SSR/MPA)
+
+Templating is an **option**, not something MSA forbids. Enable only when a
+service must render HTML itself (e.g. an edge/gateway serving an admin page).
+Most services stay gRPC-only — do not create `views/` speculatively.
+
+When enabled for `{service_name}`, add role `view`:
+
+```text
+view = views/{feature}/{page}.html | views/layouts/* | views/partials/*
+```
+
+Extra rules:
+
+- Handlers: parse → call flow → build template context → render. No DB in handlers.
+- flow returns plain data / view models — never HTML.
+- templates: presentation only; no DB/service/domain calls.
+- Template/asset bundling is wired the same way as proto: `plugin-build-ssr.sh`
+  auto-detects `{service_name}/views/` and adds a build guard for it. Implement
+  the bundling there, not as an ad-hoc one-off command.
+- If the service is gRPC-only, do **not** create `views/`.
 
 ## Roles inside `{service_name}`
 

{yjcli-0.2.4 → yjcli-0.2.5}/src/yjcli/data/skills/yj-backend-service/SKILL.md

@@ -3,7 +3,8 @@ name: yj-backend-service
 description: >-
   Single deployable backend service architecture (non-MSA). Use when editing
   backend-service/** or browser-extension/native_*/**. Language-agnostic.
-  Optional server-templating/SSR is an add-on chapter, not a separate platform.
+  Optional server-templating/SSR and optional gRPC/protobuf transport are both
+  add-on chapters, not separate platforms — choosing gRPC does not make this MSA.
   Domains are optional owned concepts (not persistence-only). Do not use for
   backend/ (MSA), frontend/, mobile-app/, pc-app/, cli/, or
   browser-extension UI/background (non-native_*) paths.
@@ -74,6 +75,26 @@ If the process owns **no** local concept (only calls remote APIs / extension mes
 - Clients in `modules`; feature orchestration + feature-local rules in `services`.
 - If a **shared** policy grows across features, prefer a small rules-only domain over stuffing `apps/`.
 
+## Optional: gRPC transport (protobuf)
+
+Protobuf/gRPC is an **option**, not backend-service's default, and choosing it
+does **not** turn this into MSA. Enable only when this single service's own
+external API is defined as proto. Unlike `backend`, there is no shared
+multi-service contract here, no fan-out to sibling services, and the
+cross-service "call only through generated clients" rule from `yj-backend-msa`
+does not apply — there is no sibling service to call.
+
+Keep the schema at `{platform}/proto/*.proto` (same reserved location
+`plugin-build-proto.sh` already checks). If more than one service under this
+platform needs its own independent proto contract at the same time, that is a
+signal the unit may belong in `backend/` (MSA) instead — do not invent a second
+proto location to work around the ambiguity.
+
+Codegen is wired the same way as MSA: `plugin-build-proto.sh` auto-detects
+`proto/` and adds a protoc codegen guard (protoc is the standard; buf is not
+used). It runs automatically as part of `build-common.sh` and is also runnable
+standalone. Implement codegen there, not as an ad-hoc one-off command.
+
 ## Optional: server templating (SSR/MPA)
 
 Templating is an **option**, not the folder identity. Enable only when the service must render HTML.
@@ -89,6 +110,9 @@ Extra rules:
 - Handlers: parse → call flow → build template context → render. No DB in handlers.
 - flow returns plain data / view models — never HTML.
 - templates: presentation only; no DB/service/domain calls.
+- Template/asset bundling is wired the same way as proto: `plugin-build-ssr.sh`
+  auto-detects `{service_name}/views/` and adds a build guard for it. Implement
+  the bundling there, not as an ad-hoc one-off command.
 - If the service is JSON-API only, do **not** create `views/`.
 
 Guide when adding SSR later:

{yjcli-0.2.4 → yjcli-0.2.5}/src/yjcli/data/skills/yj-browser-extension/SKILL.md

@@ -56,6 +56,13 @@ Feature rules and orchestration live in background flow — not in listeners/`ap
 
 - UI only; talk to background via messaging.
 
+## Contracts
+
+- Consume `backend/proto/dist/{lang}` (symlink) only through a companion
+  `native_*` host or a generated web client — do not copy `.proto` sources
+  into `browser-extension/`. Browsers rarely speak gRPC directly; route
+  through the native host or a REST/gRPC-web gateway instead.
+
 ## native_host
 
 - Folder name: `native_{name}/` under `browser-extension/`.

{yjcli-0.2.4 → yjcli-0.2.5}/src/yjcli/data/skills/yj-cli/SKILL.md

@@ -63,6 +63,12 @@ infra  = modules/{module}.{ext} # config, http, db, output formatters
 
 - Printing helpers OK; **what** to print is decided in the command (entry).
 
+## Contracts
+
+- Consume `backend/proto/dist/{lang}` (symlink) for MSA contracts when a
+  command must call backend services directly; do not copy `.proto` sources
+  into `cli/`.
+
 ## Import direction
 
 ```text

{yjcli-0.2.4 → yjcli-0.2.5}/src/yjcli/data/skills/yj-frontend/SKILL.md

@@ -63,6 +63,26 @@ Missing domain ≠ dump DTOs/utils into `main.tsx` / `App.tsx`. Keep feature wor
 - Generated UI primitives: do not hand-edit or duplicate.
 - Consume backend contracts via generated client or `backend/proto/dist/{lang}` — never copy `.proto` into frontend.
 
+## Optional: server templating (SSR)
+
+Templating is an **option**, not this app's default. Most apps stay a
+client-rendered SPA — enable only when this app must render HTML server-side
+(e.g. a lightweight SSR/SSG entry alongside the Vite build).
+
+When enabled, add sibling to `src/`:
+
+```text
+views/{page}.html | views/layouts/* | views/partials/*
+```
+
+- Template/asset bundling is wired the same way as other platforms:
+  `plugin-build-ssr.sh` auto-detects `{app_name}/views/` and adds a build
+  guard for it. Implement the bundling there, not as an ad-hoc one-off command.
+- Keep `src/` (client bundle) and `views/` (server-rendered templates)
+  separate; do not fold template markup into `pages/`/`components/`.
+- Do **not** create `views/` speculatively — it does not apply to a normal
+  client-only SPA.
+
 ## Import direction
 
 ```text

{yjcli-0.2.4 → yjcli-0.2.5}/src/yjcli/data/skills/yj-scheduler/SKILL.md

@@ -71,6 +71,31 @@ scheduler/
 - Do not import another platform's source tree; communicate through explicit
   APIs or generated contracts.
 
+## Optional: template rendering (reports/emails)
+
+Templating is an **option**, not this platform's default. Enable only when a
+job must render HTML/text output (e.g. an email digest or a generated report).
+
+When enabled for `{scheduler_name}`, add:
+
+```text
+views/{job_name}/*.html | views/layouts/* | views/partials/*
+```
+
+- flow (`services/{job_name}`) returns plain data / render context — never
+  pre-rendered HTML. Rendering happens at the point of use (e.g. before
+  sending an email), not scattered across `modules/`.
+- Template/asset bundling is wired the same way as other platforms:
+  `plugin-build-ssr.sh` auto-detects `{scheduler_name}/views/` and adds a
+  build guard for it. Implement the bundling there, not as an ad-hoc command.
+- If no job renders output, do **not** create `views/` speculatively.
+
+## Contracts
+
+- Consume `backend/proto/dist/{lang}` (symlink) for MSA contracts when a job
+  must call backend services directly; do not copy `.proto` sources into
+  `scheduler/`.
+
 ## Scheduling policy
 
 For every job, make these decisions explicit near its registration or config:

{yjcli-0.2.4 → yjcli-0.2.5}/src/yjcli/data/templates/AGENTS.md

@@ -59,11 +59,18 @@ Paths from `yjcli init` are fixed; add platform/app rows with `<path>` / `<role>
 | `CLAUDE.md` | Mirror of `AGENTS.md` — do not edit; refresh with `yjcli sync agents` |
 | `TOOLS.md` | Release-tools feature spec (version / deploy / git) |
 | `Diff.md` | User-maintained reference for project differences from yjcli defaults; yjcli never updates or restores from it |
-| `Makefile` | Root entry — run via `make <platform>`; deploy via `<platform>-deploy-development\|production`, optionally with `NAME=<service>` |
-| `make.bat` | Extensible Windows counterpart of root Makefile |
-| `<platform>/scripts/deploy-common.*` | Repository-owned shared build/package implementation |
-| `<platform>/scripts/deploy-development.*` | Repository-owned development upload/deploy implementation |
-| `<platform>/scripts/deploy-production.*` | Repository-owned production upload/deploy implementation |
+| `Makefile` | Root entry — run via `make <platform>`; build via `<platform>-build-development\|production`, deploy via `<platform>-deploy-development\|production`, optionally with `NAME=<service>` |
+| `make.bat` | Windows counterpart of root Makefile — `run.*` is native; `build-*`/`deploy-*` targets shell out to WSL (build/deploy tooling such as Docker is not native to Windows) |
+| `<platform>/scripts/build-common.sh` | Repository-owned shared build/package implementation; same file for every platform — runs every `scripts/plugin-build-*.sh` present, then its own generic build guard |
+| `<platform>/scripts/plugin-build-proto.sh` | Plugin: protoc codegen guard, self-detects `<platform>/proto/` at runtime — no platform-name branching, any platform can opt in |
+| `<platform>/scripts/plugin-build-ssr.sh` | Plugin: template/asset build guard, self-detects `<platform>/{service}/views/` per service — no platform-name branching, any platform's service can opt in |
+| `<platform>/scripts/plugin-build-docker.sh` | Plugin: docker image **build only** (no push, no swarm/stack rollout — that's a deploy-side plugin's job), self-detects `{service}/Dockerfile` per service; resolves image version from `package.json`/`pyproject.toml`, else the `VERSION` env var |
+| `<platform>/scripts/build-development.sh` | Repository-owned development build implementation (calls `build-common.sh`) |
+| `<platform>/scripts/build-production.sh` | Repository-owned production build implementation (calls `build-common.sh`) |
+| `<platform>/scripts/deploy-common.sh` | Repository-owned shared deploy orchestration; same file for every platform — calls the matching build script, then runs every `scripts/plugin-deploy-*.sh` present (none ship by default) |
+| `<platform>/scripts/deploy-development.sh` | Repository-owned development upload/deploy implementation (calls `deploy-common.sh`, then owns upload guidance) |
+| `<platform>/scripts/deploy-production.sh` | Repository-owned production upload/deploy implementation (calls `deploy-common.sh`, then owns upload guidance) |
+| `<platform>/{service}/Dockerfile`, `.dockerignore` | Docker build stub for a service, added by `yjcli service add` for deployable platforms (`backend`, `backend-service`, `frontend`, `scheduler`); language-agnostic — fails `docker build` until replaced |
 | `.gitignore` | Canonical ignore rules |
 | `.cursor/skills/` | Cursor skills (copied from package) |
 | `.claude/skills/` | Claude skills (copied from package) |
@@ -99,7 +106,11 @@ Paths from `yjcli init` are fixed; add platform/app rows with `<path>` / `<role>
 # build
 <command>
 
-# deploy (generated stubs fail until implemented)
+# build (generated stubs fail until implemented; .sh only — Windows runs via WSL)
+make <platform>-build-development [NAME=<service>]
+make <platform>-build-production [NAME=<service>]
+
+# deploy (generated stubs fail until implemented; .sh only — Windows runs via WSL)
 make <platform>-deploy-development [NAME=<service>]
 make <platform>-deploy-production [NAME=<service>]
 ```

{yjcli-0.2.4 → yjcli-0.2.5}/src/yjcli/data/templates/Makefile

@@ -2,19 +2,25 @@
 # Usage:
 #   make <platform>                 # all services under that platform (concurrent)
 #   make <platform> NAME=<service>  # one service
-# Deploy templates are platform-owned extension points. They intentionally fail
+# Build/deploy templates are platform-owned extension points. They intentionally fail
 # until the repository implements the printed build/package/upload steps.
+# Build/deploy scripts are POSIX shell (.sh) only — build/deploy tooling (Docker, etc.)
+# is not native to Windows. Run this Makefile through WSL on Windows for those targets.
 
 PLATFORMS := $(patsubst %/scripts/run.sh,%,$(wildcard */scripts/run.sh))
+BUILD_DEVELOPMENT_TARGETS := $(addsuffix -build-development,$(PLATFORMS))
+BUILD_PRODUCTION_TARGETS := $(addsuffix -build-production,$(PLATFORMS))
 DEPLOY_DEVELOPMENT_TARGETS := $(addsuffix -deploy-development,$(PLATFORMS))
 DEPLOY_PRODUCTION_TARGETS := $(addsuffix -deploy-production,$(PLATFORMS))
 
-.PHONY: help $(PLATFORMS) $(DEPLOY_DEVELOPMENT_TARGETS) $(DEPLOY_PRODUCTION_TARGETS)
+.PHONY: help $(PLATFORMS) $(BUILD_DEVELOPMENT_TARGETS) $(BUILD_PRODUCTION_TARGETS) $(DEPLOY_DEVELOPMENT_TARGETS) $(DEPLOY_PRODUCTION_TARGETS)
 
 help:
 	@echo "Usage:"
 	@echo "  make <platform>                 # start all services concurrently"
 	@echo "  make <platform> NAME=<service>  # start one service"
+	@echo "  make <platform>-build-development  [NAME=<service>]"
+	@echo "  make <platform>-build-production   [NAME=<service>]"
 	@echo "  make <platform>-deploy-development [NAME=<service>]"
 	@echo "  make <platform>-deploy-production  [NAME=<service>]"
 	@echo ""
@@ -27,7 +33,7 @@ help:
 	@echo ""
 	@echo "Example: make backend"
 	@echo "         make backend NAME=api"
-	@echo "         make backend-deploy-development NAME=api"
+	@echo "         make backend-build-development NAME=api"
 	@echo "         make backend-deploy-production NAME=api"
 
 $(PLATFORMS):
@@ -38,6 +44,14 @@ $(PLATFORMS):
 		"$@/scripts/run.sh" $(ARGS); \
 	fi
 
+$(BUILD_DEVELOPMENT_TARGETS): %-build-development:
+	@test -x "$*/scripts/build-development.sh" || (echo "missing: $*/scripts/build-development.sh"; exit 1)
+	@"$*/scripts/build-development.sh" "$(NAME)" $(ARGS)
+
+$(BUILD_PRODUCTION_TARGETS): %-build-production:
+	@test -x "$*/scripts/build-production.sh" || (echo "missing: $*/scripts/build-production.sh"; exit 1)
+	@"$*/scripts/build-production.sh" "$(NAME)" $(ARGS)
+
 $(DEPLOY_DEVELOPMENT_TARGETS): %-deploy-development:
 	@test -x "$*/scripts/deploy-development.sh" || (echo "missing: $*/scripts/deploy-development.sh"; exit 1)
 	@"$*/scripts/deploy-development.sh" "$(NAME)" $(ARGS)

{yjcli-0.2.4 → yjcli-0.2.5}/src/yjcli/data/templates/make.bat

@@ -1,19 +1,34 @@
 @echo off
 setlocal EnableExtensions EnableDelayedExpansion
-rem Deploy scripts intentionally fail until their printed implementation steps are completed.
+rem Build/deploy scripts are POSIX shell (.sh) only (Docker etc. are not native to
+rem Windows); those targets run through WSL. run.* stays native Windows.
+rem Build/deploy scripts intentionally fail until their printed implementation steps
+rem are completed.
 
 if /I "%~1"=="" goto help
 if /I "%~1"=="help" goto help
 
 set "TARGET=%~1"
+set "ACTION="
+
+set "PLATFORM=%TARGET:-build-development=%"
+if /I not "%PLATFORM%"=="%TARGET%" (
+  set "ACTION=build-development"
+  goto parse_start
+)
+set "PLATFORM=%TARGET:-build-production=%"
+if /I not "%PLATFORM%"=="%TARGET%" (
+  set "ACTION=build-production"
+  goto parse_start
+)
 set "PLATFORM=%TARGET:-deploy-development=%"
 if /I not "%PLATFORM%"=="%TARGET%" (
-  set "DEPLOY_ENV=development"
+  set "ACTION=deploy-development"
   goto parse_start
 )
 set "PLATFORM=%TARGET:-deploy-production=%"
 if /I not "%PLATFORM%"=="%TARGET%" (
-  set "DEPLOY_ENV=production"
+  set "ACTION=deploy-production"
   goto parse_start
 )
 set "PLATFORM=%TARGET%"
@@ -35,8 +50,17 @@ shift
 goto parse
 
 :run_exec
-if defined DEPLOY_ENV (
-  call "%PLATFORM%\scripts\deploy-%DEPLOY_ENV%.bat" "%NAME%"
+if defined ACTION (
+  where wsl >nul 2>&1
+  if errorlevel 1 (
+    echo wsl.exe not found. Build/deploy scripts are .sh only; install WSL to run %ACTION% on Windows.
+    exit /b 1
+  )
+  if not exist "%PLATFORM%\scripts\%ACTION%.sh" (
+    echo missing: %PLATFORM%\scripts\%ACTION%.sh
+    exit /b 1
+  )
+  wsl bash "%PLATFORM%/scripts/%ACTION%.sh" "%NAME%"
   exit /b !ERRORLEVEL!
 )
 if "%NAME%"=="" (
@@ -50,8 +74,10 @@ exit /b %ERRORLEVEL%
 echo Usage:
 echo   make.bat ^<platform^>                 # all services ^(separate windows^)
 echo   make.bat ^<platform^> NAME=^<service^>  # one service
-echo   make.bat ^<platform^>-deploy-development [NAME=^<service^>]
-echo   make.bat ^<platform^>-deploy-production  [NAME=^<service^>]
+echo   make.bat ^<platform^>-build-development  [NAME=^<service^>]  ^(via WSL^)
+echo   make.bat ^<platform^>-build-production   [NAME=^<service^>]  ^(via WSL^)
+echo   make.bat ^<platform^>-deploy-development [NAME=^<service^>]  ^(via WSL^)
+echo   make.bat ^<platform^>-deploy-production  [NAME=^<service^>]  ^(via WSL^)
 echo.
 echo Available platforms (dirs with scripts\run.bat):
 set "FOUND="
@@ -65,6 +91,6 @@ if not defined FOUND echo   ^(none — run: yjcli platform add^)
 echo.
 echo Example: make.bat backend
 echo          make.bat backend NAME=api
-echo          make.bat backend-deploy-development NAME=api
+echo          make.bat backend-build-development NAME=api
 echo          make.bat backend-deploy-production NAME=api
 exit /b 0