@soddong/agentic-runtime 0.16.0

package/docs/build.md

@@ -0,0 +1,129 @@
+# @soddong/agentic-runtime 개발 및 빌드 매뉴얼
+
+## 1. 목적
+
+본 문서는 구축 담당자가 `@soddong/agentic-runtime` 패키지를 개발, 빌드, 로컬 검증하기 위해 알아야 하는 내용을 정리합니다.
+
+운영환경 사용자는 이 문서를 볼 필요가 없습니다.
+
+공통 패키지 개발 기준은 구축 저장소의 `docs/standards/package-development-standard.md`를 따릅니다.
+
+## 2. 패키지 정보
+
+| 항목 | 값 |
+| --- | --- |
+| package | `@soddong/agentic-runtime` |
+| current version | `0.16.0` |
+| binary | `agentic` |
+| workspace | `packages/agentic-runtime` |
+
+## 3. 소스 구조
+
+```text
+packages/agentic-runtime/
+  package.json
+  README.md
+  CHANGELOG.md
+  tsconfig.json
+  src/
+    index.ts
+    cli.ts
+    database.ts
+    database/
+      migrations/
+        0001_runtime_base.sql
+  docs/
+    usage.md
+    configuration.md
+    build.md
+    publishing.md
+    delivery.md
+    operations.md
+    schema/
+      generated/
+      migrations.md
+```
+
+## 4. 개발 검증
+
+repository root에서 실행합니다.
+
+```bash
+npm install
+npm run build
+npm run typecheck
+```
+
+CLI를 로컬에서 직접 실행합니다.
+
+```bash
+node packages/agentic-runtime/dist/cli.js --version
+node packages/agentic-runtime/dist/cli.js --help
+```
+
+SQLite 테이블 설계서와 다이어그램은 `tbls`로 생성합니다.
+
+```bash
+npm run schema:doc:agentic-runtime
+```
+
+생성 산출물:
+
+```text
+packages/agentic-runtime/docs/schema/generated/README.md
+packages/agentic-runtime/docs/schema/generated/schema.json
+packages/agentic-runtime/docs/schema/generated/schema.svg
+packages/agentic-runtime/docs/schema/generated/{table-name}.svg
+```
+
+## 5. 패키징 Dry Run
+
+macOS / Linux:
+
+```bash
+npm pack --workspace @soddong/agentic-runtime --dry-run --cache /private/tmp/agentic-npm-cache
+```
+
+Windows PowerShell:
+
+```powershell
+npm pack --workspace @soddong/agentic-runtime --dry-run --cache "$env:TEMP\agentic-npm-cache"
+```
+
+확인 항목:
+
+```text
+- README.md 포함
+- CHANGELOG.md 포함
+- docs/usage.md 포함
+- docs/configuration.md 포함
+- docs/build.md 포함
+- docs/publishing.md 포함
+- docs/delivery.md 포함
+- docs/operations.md 포함
+- docs/schema/generated/README.md 포함
+- docs/schema/generated/schema.json 포함
+- docs/schema/generated/schema.svg 포함
+- docs/schema/generated/{table-name}.svg 포함
+- dist/cli.js 포함
+- dist/index.js 포함
+- package.json 포함
+- 불필요한 source/test/local file 미포함
+```
+
+## 6. Registry 정책
+
+`@soddong/agentic-runtime`의 `package.json`에는 registry URL을 고정하지 않습니다.
+
+기본 publish/install registry는 공식 npm registry입니다. 인증 정보는 외부 환경에서 제공합니다.
+
+```text
+https://registry.npmjs.org/
+NPM_TOKEN
+```
+
+## 7. 다음 절차
+
+publish 절차는 [publishing.md](./publishing.md)를 따릅니다.
+
+구축 환경에서 운영환경으로 전달할 기준은 [delivery.md](./delivery.md)를 따릅니다.

package/docs/configuration.md

@@ -0,0 +1,61 @@
+# @soddong/agentic-runtime 설정 원칙
+
+## 1. 목적
+
+본 문서는 `@soddong/agentic-runtime`이 환경 정보를 어디까지 책임지고, 어떤 정보는 외부 실행 프로젝트가 제공해야 하는지 정의합니다.
+
+## 2. 원칙
+
+`@soddong/agentic-runtime`은 환경 값을 직접 소유하지 않습니다.
+
+registry, 인증, 네트워크, 중앙 DBMS, Agent profile 같은 환경 정보는 이 패키지를 설치해서 사용하는 외부 실행 프로젝트가 제공합니다.
+
+```text
+@soddong/agentic-runtime
+  - 환경 정보의 형식과 로딩 규칙을 정의
+  - package 내부에 특정 환경 값을 고정하지 않음
+
+consumer project
+  - .npmrc
+  - .env
+  - agentic.config.*
+  - CI/CD variables
+  - network/profile 설정
+```
+
+## 3. 기본 설정 파일
+
+`agentic init`은 기본적으로 다음 설정을 생성합니다.
+
+```json
+{
+  "projectName": "my-project",
+  "runtime": {
+    "database": {
+      "type": "sqlite",
+      "path": ".agentic/platform.sqlite"
+    }
+  },
+  "modules": []
+}
+```
+
+`runtime.database.path`는 consumer project 루트 기준 상대 경로 또는 절대 경로를 사용할 수 있습니다.
+
+## 4. 설정 책임 분리
+
+| 구분 | 책임 |
+| --- | --- |
+| `@soddong/agentic-runtime` | 설정 파일 규칙, CLI 옵션, 로딩 순서, 검증 오류 메시지 |
+| consumer project | 실제 registry URL, 인증 정보, DB 연결 정보, runtime profile |
+| 구축 환경 | publish 권한, build cache, package 검증 환경 |
+| 운영환경 | install registry, network/profile, 운영 권한 정책 |
+
+## 5. 금지 사항
+
+```text
+- package.json에 registry URL 고정
+- source code에 인증 정보 포함
+- 운영환경 registry 값을 구축 환경 임시 URL로 대체
+- 개인 노트북 Docker Nexus URL을 공식 운영환경 값으로 간주
+```

package/docs/delivery.md

@@ -0,0 +1,90 @@
+# @soddong/agentic-runtime Delivery 매뉴얼
+
+## 1. 목적
+
+본 문서는 `@soddong/agentic-runtime` 패키지를 구축 환경에서 운영환경으로 전달할 때 필요한 package-specific delivery 기준을 정의합니다.
+
+publish 절차 자체는 [publishing.md](./publishing.md)를 따릅니다. 운영환경 설치와 검증은 [operations.md](./operations.md)를 따릅니다.
+
+공통 패키지 개발 및 운영환경 전달 기준은 구축 저장소의 `docs/standards/package-development-standard.md`를 따릅니다.
+
+## 2. Delivery 범위
+
+| 구분 | 포함 여부 | 설명 |
+| --- | --- | --- |
+| npm package publish | 포함 | npmjs registry에 배포 |
+| 운영환경 install 검증 | 포함 | npmjs registry 기준 설치 확인 |
+| source repository 전체 전달 | 제외 | npm package 기준 전달 |
+| 인증 정보 전달 | 제외 | 환경별 `.npmrc` 또는 보안 정책으로 관리 |
+| registry URL 하드코딩 | 제외 | 환경 설정으로 제공 |
+
+## 3. Package에 포함되는 파일
+
+`@soddong/agentic-runtime` 배포 패키지는 다음 파일을 포함해야 합니다.
+
+```text
+package/
+  package.json
+  README.md
+  CHANGELOG.md
+  dist/
+    cli.js
+    index.js
+    *.d.ts
+  docs/
+    usage.md
+    configuration.md
+    build.md
+    publishing.md
+    delivery.md
+    operations.md
+```
+
+## 4. 구축 환경 산출물 확인
+
+구축 담당자는 publish 전에 다음을 확인합니다.
+
+```bash
+npm run build
+npm run typecheck
+npm pack --workspace @soddong/agentic-runtime --dry-run
+```
+
+확인 항목:
+
+```text
+[ ] package.json의 version이 배포 대상 버전과 일치
+[ ] README.md가 사용자 시작점 역할 수행
+[ ] CHANGELOG.md에 변경 이력 반영
+[ ] docs/ 하위 상세 문서 포함
+[ ] dist/cli.js 포함
+[ ] dist/index.js 포함
+[ ] registry URL이 package.json에 고정되지 않음
+[ ] 인증 정보가 package에 포함되지 않음
+```
+
+## 5. 운영환경 전달 기준
+
+운영환경에는 다음 정보만 전달하면 됩니다.
+
+```text
+- package name: @soddong/agentic-runtime
+- install version: 0.16.0
+- CLI command: agentic
+- npmjs registry 설정 방법
+- 설치 및 실행 확인 절차
+- 문제 발생 시 확인 항목
+```
+
+운영환경 사용자는 구축 환경의 publish registry, build cache, tarball 생성 절차를 알 필요가 없습니다.
+
+## 6. Registry 기준
+
+공식 publish/install registry는 npmjs를 기준으로 합니다.
+
+```text
+publish registry: https://registry.npmjs.org/
+install registry: https://registry.npmjs.org/
+```
+
+registry 변경 이력과 과거 임시값은 [management/replacement-register.md](../../../management/replacement-register.md)에서 추적합니다.

package/docs/operations.md

@@ -0,0 +1,112 @@
+# @soddong/agentic-runtime 운영환경 매뉴얼
+
+## 1. 목적
+
+본 문서는 운영 담당자 또는 사용자가 `@soddong/agentic-runtime` 설치, registry, adapter 상태를 확인하는 절차를 정의합니다.
+
+## 2. 운영 전제
+
+| 항목 | 기준 |
+| --- | --- |
+| NPM Registry | 기본값: `https://registry.npmjs.org/` |
+| 인증 | publish 권한이 필요한 경우에만 npm token 사용 |
+| package | `@soddong/agentic-runtime` |
+| CLI | `agentic` |
+| Codex bridge | `agentic-runtime-codex@agentic-runtime` 하나만 enabled |
+
+## 3. Registry 확인
+
+```bash
+npm config get registry
+```
+
+기대 결과:
+
+```text
+https://registry.npmjs.org/
+```
+
+registry와 인증 상태를 확인합니다.
+
+```bash
+npm ping --registry=https://registry.npmjs.org/
+npm whoami --registry=https://registry.npmjs.org/
+```
+
+publish 권한이 없는 설치 사용자라면 `npm whoami`는 생략할 수 있습니다.
+
+## 4. 설치
+
+```bash
+npm install @soddong/agentic-runtime@0.16.0
+```
+
+## 5. 실행 확인
+
+```bash
+npx agentic --version
+npx agentic --help
+```
+
+기대 결과:
+
+```text
+@soddong/agentic-runtime 0.16.0
+```
+
+## 6. Codex Adapter 확인
+
+Codex는 전역 plugin bridge를 사용합니다. bridge는 하나만 유지하고, 실제 기록은 @soddong/agentic-runtime으로 초기화된 프로젝트에서만 수행합니다.
+
+```bash
+codex plugin marketplace list
+codex plugin list
+npx agentic adapter status codex
+```
+
+기준:
+
+```text
+agentic-runtime-codex@agentic-runtime installed, enabled
+```
+
+다음 selector가 installed/enabled로 남아 있으면 중복 정리 대상입니다.
+
+```text
+agentic-runtime-codex@local-agentic
+agentic-runtime-codex@agentic-sdlc
+```
+
+## 7. Publish 상태 확인
+
+현재 공식 registry publish 기준 버전은 다음과 같습니다.
+
+```text
+@soddong/agentic-runtime 0.16.0
+```
+
+registry 상태는 다음 명령으로 확인합니다.
+
+```bash
+npm view @soddong/agentic-runtime version --registry=https://registry.npmjs.org/ --prefer-online
+```
+
+기대 결과:
+
+```text
+0.16.0
+```
+
+publish 전 검증 절차는 [publishing.md](./publishing.md)를 따릅니다.
+
+## 8. 장애 확인
+
+| 증상 | 확인 |
+| --- | --- |
+| package not found | 공식 npm registry publish 여부 확인. publish 전이면 `E404`가 정상일 수 있음 |
+| authentication required | 사용자 홈 `.npmrc` 인증 정보 확인 |
+| 사설 registry 접근 시도 | `npm config get registry`와 `~/.npmrc`의 stale registry 확인 |
+| `npx agentic` 실패 | `node_modules/.bin/agentic` 파일 생성 여부 확인 |
+| 버전 불일치 | `npm view @soddong/agentic-runtime version` 결과 확인 |
+| Codex hook 중복 실행 | `codex plugin list`에서 `agentic-runtime-codex@*` 중복 installed 여부 확인 |
+| 미초기화 프로젝트 Codex hook 실패 | hook command가 optional project hook인지, `.agentic/bin/agentic-hook.mjs` 부재 시 no-op 되는지 확인 |

package/docs/publishing.md

@@ -0,0 +1,196 @@
+# @soddong/agentic-runtime Publishing 매뉴얼
+
+## 1. 목적
+
+본 문서는 `@soddong/agentic-runtime` 패키지를 NPM Registry에 publish하는 절차를 정의합니다.
+
+이 문서는 구축 담당자용입니다. 운영환경 사용자는 [usage.md](./usage.md)를 사용합니다.
+
+공통 패키지 publish 기준은 구축 저장소의 `docs/standards/package-development-standard.md`를 따릅니다.
+
+## 2. 전제
+
+| 항목 | 기준 |
+| --- | --- |
+| package | `@soddong/agentic-runtime` |
+| current version | `0.16.0` |
+| binary | `agentic` |
+| workspace | `packages/agentic-runtime` |
+| publish registry | `https://registry.npmjs.org/` |
+| install registry | `https://registry.npmjs.org/` |
+
+publish 권한은 사용자 `~/.npmrc` 또는 CI secret으로 제공합니다. token 실값은 문서, source, CI log에 기록하지 않습니다.
+
+```text
+//registry.npmjs.org/:_authToken=${NPM_TOKEN}
+```
+
+인증과 registry 연결을 먼저 확인합니다.
+
+```bash
+npm config get registry
+npm ping --registry=https://registry.npmjs.org/
+npm whoami --registry=https://registry.npmjs.org/
+```
+
+## 3. Publish 전 검증
+
+repository root에서 실행합니다.
+
+```bash
+npm install
+npm run build
+npm run typecheck
+```
+
+## 4. 패키징 Dry Run
+
+macOS / Linux:
+
+```bash
+npm pack --workspace @soddong/agentic-runtime --dry-run --cache /private/tmp/agentic-npm-cache
+```
+
+Windows PowerShell:
+
+```powershell
+npm pack --workspace @soddong/agentic-runtime --dry-run --cache "$env:TEMP\agentic-npm-cache"
+```
+
+확인 항목:
+
+```text
+- README.md 포함
+- CHANGELOG.md 포함
+- docs/ 포함
+- dist/cli.js 포함
+- dist/index.js 포함
+- package.json 포함
+- 불필요한 source/test/local file 미포함
+```
+
+## 5. Tarball 생성
+
+macOS / Linux:
+
+```bash
+npm pack --workspace @soddong/agentic-runtime --cache /private/tmp/agentic-npm-cache
+```
+
+Windows PowerShell:
+
+```powershell
+npm pack --workspace @soddong/agentic-runtime --cache "$env:TEMP\agentic-npm-cache"
+```
+
+생성 예:
+
+```text
+soddong-agentic-runtime-0.16.0.tgz
+```
+
+## 6. Publish
+
+`@soddong/agentic-runtime`의 `package.json`에는 registry URL을 고정하지 않습니다.
+
+공식 npm registry를 명시해 dry-run으로 먼저 검증합니다.
+
+macOS / Linux:
+
+```bash
+npm publish --dry-run --workspace @soddong/agentic-runtime \
+  --registry=https://registry.npmjs.org/ \
+  --access public
+```
+
+Windows PowerShell:
+
+```powershell
+npm publish --dry-run --workspace @soddong/agentic-runtime --registry=https://registry.npmjs.org/ --access public
+```
+
+dry-run에서 tarball contents, package size, files 목록, publish target을 확인한 뒤 publish합니다.
+
+macOS / Linux:
+
+```bash
+npm publish --workspace @soddong/agentic-runtime \
+  --registry=https://registry.npmjs.org/ \
+  --access public
+```
+
+Windows PowerShell:
+
+```powershell
+npm publish --workspace @soddong/agentic-runtime --registry=https://registry.npmjs.org/ --access public
+```
+
+## 7. Publish 검증
+
+공식 npm registry를 기준으로 확인합니다. publish 전에는 `npm view @soddong/agentic-runtime version`이 `E404`일 수 있으며, 이는 아직 public registry에 publish되지 않았다는 의미입니다.
+
+macOS / Linux:
+
+```bash
+npm view @soddong/agentic-runtime version \
+  --registry=https://registry.npmjs.org/
+
+npm view @soddong/agentic-runtime bin --json \
+  --registry=https://registry.npmjs.org/
+```
+
+Windows PowerShell:
+
+```powershell
+npm view @soddong/agentic-runtime version --registry=https://registry.npmjs.org/
+npm view @soddong/agentic-runtime bin --json --registry=https://registry.npmjs.org/
+```
+
+기대 결과:
+
+```text
+0.16.0
+```
+
+```json
+{
+  "agentic": "dist/cli.js"
+}
+```
+
+## 8. 사용자 프로젝트 설치 검증
+
+구축 환경에서도 운영환경 사용 방식을 별도 consumer project로 검증합니다.
+
+macOS / Linux:
+
+```bash
+TEST_DIR=/private/tmp/agentic-runtime-consumer-test
+rm -rf "$TEST_DIR"
+mkdir -p "$TEST_DIR"
+cd "$TEST_DIR"
+npm init -y
+npm install @soddong/agentic-runtime@0.16.0 \
+  --registry=https://registry.npmjs.org/
+npx agentic --version
+npx agentic --help
+```
+
+Windows PowerShell:
+
+```powershell
+$testDir = Join-Path $env:TEMP "agentic-runtime-consumer-test"
+Remove-Item -Recurse -Force $testDir -ErrorAction SilentlyContinue
+New-Item -ItemType Directory -Path $testDir | Out-Null
+Set-Location $testDir
+npm init -y
+npm install @soddong/agentic-runtime@0.16.0 --registry=https://registry.npmjs.org/
+npx agentic --version
+npx agentic --help
+```
+
+기대 결과:
+
+```text
+@soddong/agentic-runtime 0.16.0
+```

package/docs/schema/generated/README.md

@@ -0,0 +1,31 @@
+# agentic-runtime
+
+## Description
+
+Agentic Platform local execution runtime database.
+
+## Tables
+
+| Name                                                                            | Columns | Comment                                                              | Type  |
+| ------------------------------------------------------------------------------- | ------- | -------------------------------------------------------------------- | ----- |
+| [agentic_runtime_metadata](agentic_runtime_metadata.md)                         | 5       | 런타임 DB 식별과 runtime-level metadata를 관리한다.                             | table |
+| [agentic_schema_migrations](agentic_schema_migrations.md)                       | 5       | runtime 및 각 패키지의 SQLite schema migration 적용 이력을 관리한다.                | table |
+| [agentic_project_modules](agentic_project_modules.md)                           | 7       | 현재 실행 프로젝트에 등록된 Agentic package 상태를 관리한다.                            | table |
+| [agentic_user_requests](agentic_user_requests.md)                               | 5       | 사용자 지시 원문과 접수 정보를 관리한다.                                              | table |
+| [agentic_execution_runs](agentic_execution_runs.md)                             | 13      | 사용자 지시 또는 runtime command의 실행 단위를 관리한다.                              | table |
+| [agentic_execution_logs](agentic_execution_logs.md)                             | 8       | 실행 중 발생한 로그와 이벤트를 순서대로 관리한다.                                         | table |
+| [agentic_execution_outputs](agentic_execution_outputs.md)                       | 7       | 실행 결과를 구조화하여 관리한다.                                                   | table |
+| [agentic_project_bundles](agentic_project_bundles.md)                           | 13      |                                                                      | table |
+| [agentic_seed_import_runs](agentic_seed_import_runs.md)                         | 13      |                                                                      | table |
+| [agentic_seed_import_items](agentic_seed_import_items.md)                       | 14      |                                                                      | table |
+| [agentic_execution_projects](agentic_execution_projects.md)                     | 16      |                                                                      | table |
+| [agentic_execution_project_stages](agentic_execution_project_stages.md)         | 9       |                                                                      | table |
+| [agentic_execution_project_activities](agentic_execution_project_activities.md) | 13      |                                                                      | table |
+
+## Relations
+
+![er](schema.svg)
+
+---
+
+> Generated by [tbls](https://github.com/k1LoW/tbls)