mirror of
https://github.com/NomaDamas/k-skill.git
synced 2026-06-24 02:04:11 +00:00
2ff51db5d2* chore: version packages * Merge dev into main (#197) * fix(toss-securities): clarify session expiry and quote 403 handling * Clarify toss empty-output session expiry Portfolio and watchlist reads can exit successfully with empty payloads when the stored Toss session has expired. The empty-output path now verifies the session before JSON parsing and only promotes confirmed invalid auth doctor data into TossSessionExpiredError. Constraint: Scope is limited to toss-securities issue #126 follow-up on PR #192 Rejected: Treat auth doctor execution failures as expired sessions | unsupported or failing doctor output is inconclusive without parsed session.valid=false Confidence: high Scope-risk: narrow Directive: Keep empty-result session expiry classification tied to explicit auth doctor confirmation Tested: npm run test --workspace toss-securities; npm run lint --workspace toss-securities; npm run ci; manual mock tossctl blank stdout invalid/inconclusive doctor checks * Avoid false session-expiry labels for validation errors The toss wrapper now treats bare validation_error text as an upstream command failure instead of a session-expired signal. Structured auth doctor JSON remains the source of truth for empty portfolio/watchlist invalid-session promotion, while known stored-session-invalid stderr still maps to TossSessionExpiredError.\n\nConstraint: PR #192 follow-up must stay scoped to issue #126 toss-securities behavior.\nRejected: Keep validation_error in the global regex | it mislabels auth doctor transport failures and quote 403 validation errors as session expiry.\nConfidence: high\nScope-risk: narrow\nDirective: Do not broaden the free-text session classifier without regressions for auth doctor and quote upstream validation failures.\nTested: npm run lint --workspace toss-securities; npm run test --workspace toss-securities; npm run ci; manual mock tossctl validation_error checks; architect verification CLEAR\nNot-tested: Live tossctl network/auth session against real Toss upstream * Align court auction lookup with monthly site search (#196) The court auction notice page posts a YYYYMM search key from its 조회 button and returns a month of rows. Keep day inputs as a compatibility filter over the monthly response and normalize the current nested detail payload shape. Constraint: courtauction.go.kr has no public API and blocks bursty automated calls. Rejected: querying every day independently | the upstream search surface is month-based and day calls return false empty results. Confidence: high Scope-risk: narrow Directive: Preserve the site-observed YYYYMM notice search contract unless the PGJ143M01 XHR changes again. Tested: npm --workspace packages/court-auction-notice-search test; npm run ci; live 서울중앙지방법원 2026-05 notice/detail smoke lookup. Not-tested: PR CI after push. Co-authored-by: OmX <omx@oh-my-codex.dev> * Guide crawler skills toward reusable discovery (#195) * chore: version packages * Guide crawler skills toward reusable discovery Constraint: User requested insane-search-style guidance for future crawling k-skills without unrelated implementation changes. Rejected: Adding crawler code or a standalone template | too broad for a docs guidance change and risks dependency creep. Confidence: high Scope-risk: narrow Directive: Keep site-specific access details inside individual skills after a site-agnostic discovery pass. Tested: npm run ci Not-tested: Live crawler behavior; documentation-only change. * Clarify crawler skill discovery guidance Constraint: Crawling k-skills need site-dependent recipes, but should derive them through a reusable discovery pass. Rejected: Leaving guidance only in docs/adding-a-skill.md | AGENTS.md and CLAUDE.md also guide future agents. Confidence: high Scope-risk: narrow Directive: Use site-agnostic discovery to find, then explicitly package, the target site's stable access path. Tested: npm run ci Not-tested: Live crawler behavior; documentation-only change. --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * Ground corporate registration guidance in official form sources Keep the consulting skill focused on draft/checklist support while pointing users to current IROS and law.go.kr form sources for submission-ready artifacts. Constraint: official registry forms can change outside the repository and must be re-downloaded at use time Rejected: committing copied official HWP/HWPX/PDF forms | they would become stale and risk misleading users Confidence: high Scope-risk: narrow Directive: do not treat Markdown templates as substitutes for official registry submission forms Tested: npm test * Ground incorporation drafting in real HWP forms Bundle official court incorporation forms plus public startup incorporation attachments, and make rhwp-filled HWP outputs the default drafting path for the corporate-registration skill. Replace the listed-company articles reference with a startup-suitable Ministry of Justice stock-company form and record source manifests for bundled binaries. Constraint: user requires actual sourced HWP templates, not generated placeholder binaries. Rejected: markdown-only drafting | it cannot produce submission-shaped Korean registry forms. Rejected: listed-company standard articles as the default reference | it is mismatched for typical startup incorporation. Confidence: high Scope-risk: moderate Directive: keep bundled HWP forms source-backed, sanitized, and edited only through copied working files. Tested: node --test scripts/skill-docs.test.js; npm run lint; k-skill-rhwp info on bundled HWP files; kordoc conversion spot checks. Not-tested: manual opening every HWP in Hancom Office and live registry submission. Co-authored-by: OmX <omx@oh-my-codex.dev> * Streamline corporate registration forms workflow Prioritize saved HWP forms for ordinary stock-company promoter incorporations, make required court-registry receipts and director identity certificates explicit, and remove the redundant markdown articles template so the skill stays HWP-first. Constraint: 법원등기소 기준 체크리스트 must include fee receipts, director seal/signature certificates, and resident-record documents. Rejected: Keeping a separate markdown articles template | duplicated the stored HWP articles workflow and encouraged non-HWP drafting. Confidence: high Scope-risk: narrow Directive: Keep corporate-registration-consulting focused on stored HWP form copies and explicit issued-document checklists. Tested: node --test --test-name-pattern 'corporate-registration-consulting' scripts/skill-docs.test.js; node --check scripts/skill-docs.test.js; ./scripts/validate-skills.sh; git diff --check Not-tested: Full npm run ci was not run because this is a skill documentation/template refactor, not release or package automation. --------- Co-authored-by: galvaomica <galvaomica@galvaomicaui-MacBookAir.local> Co-authored-by: OmX <omx@oh-my-codex.dev> Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * chore: version packages (#198) Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * feat(realtyprice): add address parsing and sido code mapping Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * fix(realtyprice): use string sido codes for consistency with upstream API * feat(realtyprice): add response normalization and buildResponse Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * feat(realtyprice): add upstream cascade fetch functions with timeout Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * feat(realtyprice): add lookupGongsijiga orchestrator with region matching Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * feat(realtyprice): add simple in-memory cache with TTL Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * feat(proxy): register GET /realtyprice route with caching Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * feat: add gongsijiga-search SKILL.md Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * chore: add changeset for gongsijiga-search Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * fix(realtyprice): align with actual realtyprice.kr API response format - Response wraps data in model.list (not bjdList/gsiList) - Field names are code/name (not bjd_cd/bjd_nm) - bun2 empty → send "0000" (not empty string) - eupmyeondong matching: try full string match first (API returns combined "면 리" names like "청계면 청천리") Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix(gongsijiga-search): align /realtyprice route with v1 API convention - Change route from /realtyprice to /v1/realtyprice for consistency with other proxy endpoints. - Add realtypriceConfigured flag to /health upstreams. - Normalize address cache key by collapsing multiple whitespaces. - Update SKILL.md and README.md to reflect the new v1 path. * feat(gongsijiga-search): add Sejong special-city support - parseAddress: allow 3-token minimum for Sejong (no sigungu) and set sigungu to empty string. - lookupGongsijiga: skip sigungu lookup for Sejong (sidoCode 29), use fixed sggCode 36110. - Add Sejong parseAddress and lookupGongsijiga test cases. - Update SKILL.md with Sejong address format examples. * refactor(gongsijiga-search): split realtyprice.kr lookup into standalone package realtyprice.kr is a fully public endpoint that needs no API key, so per the new k-skill-proxy inclusion rule (proxy is for keyed upstreams only) the helper now ships as `gongsijiga-search` and is invoked directly from the user's machine. - new workspace package packages/gongsijiga-search/ following the blue-ribbon-nearby/coupang-product-search convention (publishConfig, files, repository, keywords) - remove /v1/realtyprice route, realtyprice.js, realtyprice.test.js, and the realtypriceConfigured health flag from k-skill-proxy - document the inclusion rule in AGENTS.md and CLAUDE.md so future skills default to direct calls when no key is required - advertise the new skill in README.md, docs/install.md, and add docs/features/gongsijiga-search.md - drop the hardcoded toss-securities lockfile version assertion that pinned a workspace version (would block changesets version-packages) and document the anti-pattern in AGENTS.md / CLAUDE.md - changesets: refresh the proxy refactor message and add a patch changeset so the new gongsijiga-search package gets published --------- Co-authored-by: Jeffrey (Dongkyu) Kim <vkehfdl1@gmail.com> Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: galvaomica <galvaomica@galvaomicaui-MacBookAir.local> Co-authored-by: OmX <omx@oh-my-codex.dev> Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
22 lines
2.3 KiB
Markdown
22 lines
2.3 KiB
Markdown
# k-skill
|
|
|
|
## Testing anti-patterns
|
|
|
|
- **Never write tests that assert `.changeset/*.md` files exist.** Changesets are consumed (deleted) by `changeset version` during the release flow. Any test guarding changeset file presence will break CI on the version-bump commit and block the release pipeline.
|
|
- **Never write tests that pin a workspace package's `version` field** (in `package.json` or `package-lock.json`). `changeset version` bumps these on every release, so any hardcoded version assertion will fail the next release commit and block the npm publish pipeline. Stable invariants like `name`, `license`, `engines.node`, or workspace link metadata are fine to assert; the `version` is not.
|
|
|
|
## Crawling/search skill authoring
|
|
|
|
- 크롤링/검색 k-skill의 목표는 최종적으로 대상 사이트에 맞는 site-dependent 접근 방법을 스킬에 패키징하는 것이다.
|
|
- 다만 방법을 고정하기 전에 `insane-search`식 site-agnostic discovery를 먼저 수행한다: 공개 입구, 브라우저에서 보이는 데이터 흐름, RSS/sitemap/정적 JSON/모바일 페이지, 차단·빈 응답·로그인벽 실패 모드를 확인한다.
|
|
- 발견한 검색 URL, 필수 입력값, 결과 해석 규칙, fallback 순서, 실패 모드는 `SKILL.md`와 helper 코드에 명확히 남긴다. 자세한 체크리스트는 `docs/adding-a-skill.md`를 따른다.
|
|
- 새 크롤링 dependency는 기본값으로 추가하지 말고 기존 기능, 공개 endpoint, 좁은 proxy route로 해결 가능한지 먼저 확인한다.
|
|
|
|
## Proxy server development
|
|
|
|
- 개발 repo: `/Users/jeffrey/Projects/k-skill` (이 디렉토리, `dev` 브랜치)
|
|
- 프로덕션 배포본: `~/.local/share/k-skill-proxy` (main 브랜치 단독 clone)
|
|
- **cron job** 이 매시 정각에 `origin/main` fetch → fast-forward pull → pm2 restart 실행
|
|
- 따라서 proxy route 변경은 **main에 merge되어야 프로덕션에 반영**된다. dev에서 코드를 바꿔도 프로덕션 proxy에는 영향 없음.
|
|
- 로컬 테스트는 `node packages/k-skill-proxy/src/server.js` 로 직접 실행하거나 `node --test packages/k-skill-proxy/test/server.test.js` 로 확인.
|
|
- **Proxy 편입 규칙**: k-skill-proxy에 route를 추가하려면 upstream이 API 키를 필요로 해야 한다. 공개 엔드포인트(키 불필요)는 skill 코드에서 직접 호출하고 프록시를 거치지 않는다.
|