agentic-dev 0.2.7 → 0.2.8

package/README.md

@@ -1,135 +1,53 @@
-# templates
+# agentic-dev
 
-제품으로 바로 수렴 가능한 client/server 템플릿 모음이자 downstream 저장소가 그대로 복제하는 canonical template repo다.
+`agentic-dev`는 `say828`의 공개 `template-*` 레포를 설치하는 scaffold CLI다.
 
-포함 템플릿:
-
-- [landing](./client/landing): 마케팅/브랜드 랜딩 패턴
-- [web](./client/web): 일반 제품형 웹 앱 shell, dashboard/list/detail 패턴
-- [mobile](./client/mobile): 다국어/현장 업무형 모바일 IN workspace 패턴
-- [admin](./client/admin): 운영 콘솔형 shell, sidebar/topbar/drawer/table 패턴
-- [server](./server): HTTP 기반 hexagonal/DDD 서버 패턴
-
-공통 원칙:
-
-- 프론트엔드는 `pnpm workspace + React + Vite + Tailwind` 기반
-- `shadcn/ui-style` primitive를 직접 포함
-- 제품 DOM은 유지하고, 스타일 조정값은 `theme.ts` + CSS custom properties로 노출
-- proof/spec 전용 DOM 복제 대신 fixture data + parameter surface로 정렬
-- `server`는 hexagonal architecture 기준으로 `contracts + application + domain + infrastructure`를 사용
-- `landing`, `web`, `mobile`, `admin`은 실제 `/api/v1/auth/login`과 `/api/v1/auth/me`를 사용하는 기준 템플릿이다.
-- runtime baseline은 루트 `compose.yml`을 기준으로 유지하고, 여기서 4개 frontend surface, `server`, 기본 `postgres`, optional DB profile을 함께 올린다.
-- agentic baseline은 `.claude`, `.codex`, `.agent`를 함께 유지하고 downstream repo가 role agent, skill alias, Ralph harness를 그대로 가져가도록 설계한다.
-- `sdd/03_build`는 단순 구현 목록이 아니라 실제 runtime assembly를 따라 읽는 AST-style current-state 설명을 기준으로 유지한다.
-
-SDD / delivery 원칙:
-
-- 설계, 계획, 구현, 검증, 운영 문서는 모두 `sdd/`가 canonical root다.
-- `sdd/`는 history 누적이 아니라 current-state durable 문서만 유지한다.
-- `02_plan`은 에이전트의 현재 개발 계획을 관리하고, feature는 `<domain>_todos.md`, screen은 `<service>_todos.md`로 유지한다.
-- retained verification summary는 `sdd/03_verify`를 canonical root로 사용한다.
-- 템플릿 runtime baseline은 root `compose.yml` dev-focused stack이고, dedicated host용 DEV(개발계)/PROD compose overlay는 `infra/compose/`에 둔다.
-- current canonical delivery split은 `AWS edge/domain -> OpenStack backend compute -> AWS data plane`이다.
-- DEV(개발계) 반영이 필요한 작업은 `build -> main push -> DEV deploy -> DEV verify` 순서를 기본으로 사용한다.
-
-문서:
-
-- [UI Contract Projection](./sdd/99_toolchain/01_automation/ui-contract-projection.md): 스킬/CLI 공통 projection 계약
-- [Infra Compose](./infra/compose/README.md): root compose baseline과 dedicated DEV(개발계)/PROD compose overlay
-- [Terraform Layout](./infra/terraform/README.md): provider-first canonical infra layout
-- [OpenStack Terraform](./infra/terraform/openstack/README.md): OpenStack compute baseline
-- [AST Build Governance](./sdd/02_plan/03_architecture/build_ast_runtime_tree_governance.md): `sdd/03_build` runtime-tree governance
-
-설치형 scaffold:
+## 사용법
 
 ```bash
 npx agentic-dev
 ```
 
-또는 비대화형으로:
+또는 비대화형:
 
 ```bash
-npx agentic-dev init my-app --template template-web
-npx agentic-dev init my-app --template template-web --skip-bootstrap
+npx agentic-dev init my-app --template template-fullstack-mono --yes
+npx agentic-dev init my-app --template template-web --yes --skip-bootstrap
 ```
 
-설치 프로세스:
+## 동작
 
-1. `npx agentic-dev` 또는 `npx agentic-dev init <dir>`
-   - 프로젝트 디렉터리를 입력받는다.
-2. 공개 `say828/template-*` 레포 목록에서 템플릿을 선택한다.
-   - repo name 또는 숫자 선택을 모두 지원한다.
-3. 선택한 template repo를 새 폴더로 clone/copy 한다.
-   - `template-*` 패턴이 아닌 값은 거부한다.
+1. GitHub에서 공개 `say828/template-*` 레포 목록을 조회한다.
+2. 사용자가 프로젝트 디렉터리와 템플릿 레포를 고른다.
+3. 선택한 레포를 새 디렉터리로 복제한다.
 4. `.env.example`이 있으면 `.env`를 자동 생성한다.
-5. `pnpm install`과 `pnpm exec playwright install chromium`을 자동 실행한다.
-6. `npm run ui:parity:bootstrap`을 자동 실행한다.
-   - `--skip-bootstrap`을 주면 이 단계만 건너뛴다.
-
-CLI가 하는 일:
-
-- 공개 `say828/template-*` 레포를 GitHub API로 조회한다.
-- 사용자 입력을 받아 template repo를 선택한다.
-- 선택된 repo를 target directory에 설치하고 `.env`, dependencies, Chromium, bootstrap까지 자동 처리한다.
-- invalid repo name이나 `template-*`가 아닌 값은 즉시 거부한다.
-- `--skip-bootstrap`을 주면 설치까지만 하고 bootstrap은 멈춘다.
+5. `pnpm install`을 자동 실행한다.
+6. 템플릿의 `repo-contract.json`에서 `frontend.default_target`을 읽는다.
+7. 그 target에 대해 `playwright install chromium`을 실행한다.
+8. 그 target에 대해 parity bootstrap을 실행한다.
 
-Parity 명령:
+`frontend.default_target`이 있으면 multi-surface 템플릿도 그대로 지원한다. 예를 들어 `template-fullstack-mono`는 `client/web`과 `client/admin`을 함께 포함하지만 기본 bootstrap 대상은 `web`이다.
 
-- `npm run ui:parity:init`
-  - repo contract alias, parity contract, route-gap 산출물을 초기화한다.
-- `npm run ui:parity:bootstrap`
-  - `init -> build -> preview -> materialize reference -> plan_audit gate -> proof gate`를 한 번에 실행한다.
-- `npm run ui:parity:proof`
-  - 기존 parity contract를 기준으로 proof만 다시 실행한다.
-
-주요 parity 산출물:
-
-- contract: `sdd/02_plan/10_test/templates/ui_parity_web_contract.yaml`
-- route-gap report: `sdd/02_plan/99_generated/from_planning/ui_parity/`
-- verification summary: `sdd/03_verify/10_test/ui_parity/`
-- preview log: `sdd/03_verify/10_test/ui_parity/web-preview.log`
-
-GitHub token 운영:
-
-- 실제 token 값은 repo 파일에 저장하지 않는다.
-- GitHub CLI나 자동화는 `GH_TOKEN` 또는 별도 wrapper가 있다면 `AGENTIC_GITHUB_TOKEN` 같은 환경변수에서 읽도록 운영한다.
-- 이미 대화나 로그에 노출된 token은 재사용하지 않고 즉시 폐기 후 새로 발급하는 것이 맞다.
-
-
-개발용 compose baseline:
+## 예시
 
 ```bash
-cp .env.example .env
-docker compose up --build
+mkdir my-fullstack-app
+cd my-fullstack-app
+npx agentic-dev init . --template template-fullstack-mono --yes
 ```
 
-기본 compose 포트:
-
-- `client/landing`: `3000`
-- `client/web`: `3001`
-- `client/mobile`: `3002`
-- `client/admin`: `4000`
-- `server/http`: `8000`
-
-기본 로그인 계정:
-
-- `admin@example.com` / `<CHANGE_ME>`
-- `operator@example.com` / `<CHANGE_ME>`
-
-DB adapter 전환:
+설치가 끝나면 CLI가 아래까지 자동 처리한다.
 
-- 기본: `SERVER_DATABASE_BACKEND=postgres`
-- 선택 가능: `postgres`, `mysql`, `mariadb`, `mongodb`, `memory`
-- optional DB 컨테이너는 compose profile로 포함돼 있다:
-  - `docker compose --profile mysql up --build`
-  - `docker compose --profile mariadb up --build`
-  - `docker compose --profile mongo up --build`
+- `.env.example -> .env`
+- `pnpm install`
+- `pnpm --dir client/web exec playwright install chromium`
+- `bash sdd/99_toolchain/01_automation/agentic-dev/bootstrap_frontend_parity.sh . web`
 
-Agentic baseline:
+## 옵션
 
-- `.claude/agents/`: Claude role agent prompt surface
-- `.claude/skills/sdd`: Claude SDD canonical skill
-- `.codex/skills/SKILL.md`: Codex root skill index
-- `.codex/skills/sdd/`: Codex SDD canonical skill
-- `.agent/ralph.sh`, `.agent/ralph-supervisor.sh`: bounded Ralph loop runner
+- `--template`, `-t`: template repo name 또는 suffix
+- `--owner`: GitHub owner. 기본값 `say828`
+- `--force`: 비어 있지 않은 디렉터리 허용
+- `--yes`, `-y`: interactive prompt 생략
+- `--skip-bootstrap`: install까지만 하고 bootstrap은 생략
+- `--help`, `-h`: 도움말 출력

package/lib/scaffold.mjs

@@ -255,6 +255,57 @@ function detectClientSurfaces(destinationRoot) {
     .sort();
 }
 
+function repoContractPath(destinationRoot) {
+  return path.join(
+    destinationRoot,
+    "sdd/99_toolchain/01_automation/agentic-dev/repo-contract.json",
+  );
+}
+
+function readJsonFile(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf-8"));
+  } catch (error) {
+    throw new Error(`Failed to parse JSON file: ${filePath}`);
+  }
+}
+
+function resolveBootstrapTarget(destinationRoot) {
+  const contract = readJsonFile(repoContractPath(destinationRoot));
+  const defaultTargetName = contract?.frontend?.default_target;
+  const targetConfig =
+    typeof defaultTargetName === "string"
+      ? contract?.frontend?.targets?.[defaultTargetName]
+      : null;
+
+  if (typeof targetConfig?.dir === "string" && targetConfig.dir.length > 0) {
+    return {
+      name: defaultTargetName,
+      dir: targetConfig.dir,
+    };
+  }
+
+  const clientSurfaces = detectClientSurfaces(destinationRoot);
+  if (clientSurfaces.length === 1) {
+    return {
+      name: clientSurfaces[0],
+      dir: path.join("client", clientSurfaces[0]),
+    };
+  }
+
+  if (clientSurfaces.length > 1) {
+    throw new Error(
+      "Template repo has multiple client surfaces. Add frontend.default_target to sdd/99_toolchain/01_automation/agentic-dev/repo-contract.json.",
+    );
+  }
+
+  return null;
+}
+
 function validateTemplateRepoContents(destinationRoot, templateRepo) {
   const requiredPaths = [
     ".env.example",
@@ -272,13 +323,8 @@ function validateTemplateRepoContents(destinationRoot, templateRepo) {
   }
 }
 
-function runInstallSteps(destinationRoot) {
+function runInstallSteps(destinationRoot, bootstrapTarget) {
   maybeCreateEnvFile(destinationRoot);
-  const clientSurfaces = detectClientSurfaces(destinationRoot);
-  if (clientSurfaces.length !== 1) {
-    throw new Error(`Expected exactly one client surface in template repo, found ${clientSurfaces.length}.`);
-  }
-  const clientDir = path.join("client", clientSurfaces[0]);
 
   const pnpmCommand = ensurePnpm();
   runCommand(pnpmCommand[0], [...pnpmCommand.slice(1), "install"], {
@@ -286,19 +332,32 @@ function runInstallSteps(destinationRoot) {
     label: "Installing workspace dependencies",
   });
 
-  runCommand(
-    pnpmCommand[0],
-    [...pnpmCommand.slice(1), "--dir", clientDir, "exec", "playwright", "install", "chromium"],
-    {
-      cwd: destinationRoot,
-      label: "Installing Playwright Chromium",
-    },
-  );
+  const executedSteps = ["pnpm install"];
+
+  if (bootstrapTarget) {
+    runCommand(
+      pnpmCommand[0],
+      [
+        ...pnpmCommand.slice(1),
+        "--dir",
+        bootstrapTarget.dir,
+        "exec",
+        "playwright",
+        "install",
+        "chromium",
+      ],
+      {
+        cwd: destinationRoot,
+        label: `Installing Playwright Chromium for ${bootstrapTarget.name}`,
+      },
+    );
+    executedSteps.push(`pnpm --dir ${bootstrapTarget.dir} exec playwright install chromium`);
+  }
 
-  return ["pnpm install", "pnpm exec playwright install chromium"];
+  return executedSteps;
 }
 
-function runBootstrapStep(destinationRoot) {
+function runBootstrapStep(destinationRoot, bootstrapTarget) {
   const bootstrapScript = bootstrapScriptPath(destinationRoot);
   if (!fs.existsSync(bootstrapScript)) {
     throw new Error(
@@ -306,12 +365,17 @@ function runBootstrapStep(destinationRoot) {
     );
   }
 
-  runCommand("bash", [bootstrapScript, "."], {
+  const args = [bootstrapScript, "."];
+  if (bootstrapTarget?.name) {
+    args.push(bootstrapTarget.name);
+  }
+
+  runCommand("bash", args, {
     cwd: destinationRoot,
     label: "Running frontend parity bootstrap",
   });
 
-  return ["bootstrap_frontend_parity.sh ."];
+  return [bootstrapTarget?.name ? `bootstrap_frontend_parity.sh . ${bootstrapTarget.name}` : "bootstrap_frontend_parity.sh ."];
 }
 
 export function scaffoldFromTemplateRepo({ destinationRoot, templateRepo }) {
@@ -335,16 +399,15 @@ export function installTemplateRepo({
 }) {
   scaffoldFromTemplateRepo({ destinationRoot, templateRepo });
   validateTemplateRepoContents(destinationRoot, templateRepo);
+  const bootstrapTarget = resolveBootstrapTarget(destinationRoot);
 
-  const executedSteps = runInstallSteps(destinationRoot);
+  const executedSteps = runInstallSteps(destinationRoot, bootstrapTarget);
   if (!skipBootstrap) {
-    executedSteps.push(...runBootstrapStep(destinationRoot));
+    executedSteps.push(...runBootstrapStep(destinationRoot, bootstrapTarget));
   }
-  const clientSurfaces = detectClientSurfaces(destinationRoot);
-  const bootstrapHint =
-    clientSurfaces.length === 1
-      ? `cd client/${clientSurfaces[0]} && npm run ui:parity:bootstrap`
-      : "npm run ui:parity:bootstrap";
+  const bootstrapHint = bootstrapTarget
+    ? `cd ${bootstrapTarget.dir} && npm run ui:parity:bootstrap`
+    : "bash sdd/99_toolchain/01_automation/agentic-dev/bootstrap_frontend_parity.sh .";
   return {
     destinationRoot,
     templateRepo: templateRepo.name,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agentic-dev",
-  "version": "0.2.7",
-  "description": "Scaffold an agentic template repo with the selected frontend surface and shared toolchain assets.",
+  "version": "0.2.8",
+  "description": "Scaffold a public say828/template-* repo and run install/bootstrap automatically.",
   "type": "module",
   "packageManager": "pnpm@10.32.0",
   "bin": {
@@ -28,7 +28,7 @@
     "pnpm-workspace.yaml"
   ],
   "scripts": {
-    "smoke:init": "node ./bin/agentic-dev.mjs init ./.tmp-agentic-smoke --template template-web --yes --force"
+    "smoke:init": "node ./bin/agentic-dev.mjs init ./.tmp-agentic-smoke --template template-fullstack-mono --yes --force"
   },
   "keywords": [
     "agentic",