@steercards/agent-tools 0.1.0 → 0.1.1

package/dist/install.d.ts

@@ -1,9 +1,5 @@
-export declare const packageRoot: string;
+export { packageRoot, packageInfo } from './package.js';
 export declare const skillRoot: string;
-export declare const packageInfo: {
-    name: string;
-    version: string;
-};
 export declare const clients: readonly ["claude-code", "codex", "codex-app", "codex-cli", "cursor", "claude-desktop"];
 export type Client = typeof clients[number];
 export declare function clientConfig(client: string, options?: {

package/dist/install.js

@@ -1,12 +1,11 @@
 import { readFile, readdir, mkdir, lstat, rename, rm, mkdtemp, writeFile } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
 import { homedir } from 'node:os';
-import { fileURLToPath } from 'node:url';
 import { zipSync } from 'fflate';
 import { validateMcpUrl } from './config.js';
-export const packageRoot = fileURLToPath(new URL('../', import.meta.url));
+import { packageRoot, packageInfo } from './package.js';
+export { packageRoot, packageInfo } from './package.js';
 export const skillRoot = join(packageRoot, 'skills', 'steercards');
-export const packageInfo = JSON.parse(await readFile(join(packageRoot, 'package.json'), 'utf8'));
 export const clients = ['claude-code', 'codex', 'codex-app', 'codex-cli', 'cursor', 'claude-desktop'];
 export function clientConfig(client, options = {}) {
     if (!clients.includes(client))

package/dist/package.d.ts

@@ -0,0 +1,5 @@
+export declare const packageRoot: string;
+export declare const packageInfo: {
+    name: string;
+    version: string;
+};

package/dist/package.js

@@ -0,0 +1,5 @@
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
+export const packageRoot = fileURLToPath(new URL('../', import.meta.url));
+export const packageInfo = JSON.parse(await readFile(join(packageRoot, 'package.json'), 'utf8'));

package/dist/runtime.js

@@ -2,6 +2,7 @@ import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
 import { CallToolResultSchema, ListToolsResultSchema, ToolListChangedNotificationSchema, } from '@modelcontextprotocol/sdk/types.js';
 import { validateMcpUrl } from './config.js';
+import { packageInfo } from './package.js';
 /** Extract only a small, machine-readable code; arbitrary error prose stays private. */
 async function httpErrorCode(response, agentKey) {
     if (!response.headers.get('content-type')?.toLowerCase().includes('application/json') || !response.body) {
@@ -59,7 +60,7 @@ export class Runtime {
             return this.client;
         if (!this.connecting) {
             this.connecting = (async () => {
-                const client = new Client({ name: '@steercards/agent-tools', version: '0.1.0' });
+                const client = new Client({ name: packageInfo.name, version: packageInfo.version });
                 client.setNotificationHandler(ToolListChangedNotificationSchema, async () => { this.catalog = undefined; });
                 const endpoint = this.config.url;
                 const transport = new StreamableHTTPClientTransport(new URL(endpoint), {

package/dist/server.js

@@ -2,6 +2,7 @@ import { readFile } from 'node:fs/promises';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ErrorCode, ListResourcesRequestSchema, ListToolsRequestSchema, McpError, ReadResourceRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { packageInfo } from './package.js';
 const guideTopics = ['overview', 'discovery', 'cards', 'profiles', 'claims-runs', 'context', 'files', 'collaboration'];
 const guideUri = 'steercards://guide/';
 const instructions = 'Steercards tools use progressive discovery. In compact mode search tool metadata, describe the selected tool to obtain its current schema, then call it with matching arguments. Read the Steercards guide for workflows. Tool schemas are fetched from the authenticated upstream server. Respect isError and structuredContent. Never automatically retry a mutation after a network failure; read current state first. The upstream rate limit is 120 requests per minute; follow Retry-After.';
@@ -54,7 +55,7 @@ function assertKeys(args, keys) {
 export function createServer(runtime, { mode }) {
     if (mode !== 'compact' && mode !== 'full')
         throw new Error('Server mode must be compact or full.');
-    const server = new Server({ name: '@steercards/agent-tools', version: '0.1.0' }, {
+    const server = new Server({ name: packageInfo.name, version: packageInfo.version }, {
         capabilities: { tools: {}, resources: {} }, instructions,
     });
     server.setRequestHandler(ListToolsRequestSchema, async () => ({

package/docs/releases.md

@@ -4,7 +4,14 @@
 
 ## 최초 설정
 
-1. npm의 `steercards` 조직과 패키지 쓰기 권한을 확인합니다. 아직 존재하지 않는 패키지에는 일반 trusted publisher 설정을 추가할 수 없습니다. 첫 버전부터 GitHub Actions로 게시하려면 npm 11.15.0 이상에서 로그인하고 검증한 소스를 `npm stage publish --access public`로 준비합니다. [staged publishing](https://docs.npmjs.com/staged-publishing/)은 새 패키지에 공개 placeholder `0.0.0-stage`를 생성합니다. 실제 `0.1.0`은 승인 전까지 설치할 수 없습니다.
+1. npm의 `steercards` 조직과 패키지 쓰기 권한을 확인합니다. trusted publisher는 패키지가 레지스트리에 존재해야 설정할 수 있습니다. 최초 `0.1.0`은 검사한 tarball을 유지관리자의 npm 로그인·2FA로 일반 게시합니다.
+
+   ```sh
+   npm publish /absolute/path/steercards-agent-tools-0.1.0.tgz --access public --ignore-scripts
+   npm view @steercards/agent-tools@0.1.0 version dist.integrity
+   ```
+
+   로컬 최초 게시에는 provenance가 없습니다. 다음 `0.1.1`은 아래 OIDC 절차로 게시하여 provenance를 확인합니다. 이미 게시한 버전은 덮어쓸 수 없습니다.
 2. GitHub 저장소의 Settings → Environments에 `npm` 환경을 만듭니다. 릴리스 권한을 가진 유지관리자만 릴리스 태그를 만들 수 있도록 저장소 ruleset과 환경 보호 규칙을 관리합니다.
 3. npm 패키지 Settings → Trusted Publisher에 아래 값을 등록합니다. 환경 이름까지 대소문자를 정확히 맞춥니다.
 
@@ -18,16 +25,16 @@
    | Allowed actions | `npm publish` 허용 |
 
    신규 설정은 staged publish만 기본 허용할 수 있으므로 직접 게시 권한을 명시적으로 켭니다. 워크플로는 장기 npm 토큰 없이 GitHub OIDC로 인증합니다. `NPM_TOKEN`·`NODE_AUTH_TOKEN` secret은 추가하지 않습니다.
-4. placeholder로 시작했다면 npm staged packages 화면이나 `npm stage` 명령으로 준비한 `0.1.0`을 reject합니다. staged 버전 제거와 `npm view @steercards/agent-tools@0.1.0`의 미게시 상태를 확인한 뒤 아래 GitHub Release 절차를 진행합니다. 같은 버전의 staged → reject → OIDC 직접 게시 전환은 최초 설정에서 실제 레지스트리 상태로 확인해야 합니다. staged 버전을 먼저 approve하면 같은 버전을 Actions에서 다시 게시할 수 없습니다. 새 trusted publisher는 등록 후 2일 안에 첫 게시를 성공해야 검증되므로 실제 게시를 바로 이어갈 때 등록합니다. 토큰 게시를 제한하려면 OIDC 확인 후 npm 패키지의 Publishing access를 **Require two-factor authentication and disallow tokens**로 설정합니다.
+4. 새 trusted publisher는 등록 후 2일 안에 첫 게시를 성공해야 검증됩니다. 다음 버전 PR과 검사가 준비되어 실제 OIDC 게시를 바로 이어갈 때 등록합니다. OIDC 확인 후 npm 패키지의 Publishing access를 **Require two-factor authentication and disallow tokens**로 설정합니다.
 
 ## 새 버전 게시
 
-1. 버전 변경은 별도 PR로 검토합니다. `npm version patch --no-git-tag-version`(또는 `minor`/`major`)으로 `package.json`과 `package-lock.json`의 버전을 함께 올리고 main에 병합합니다. 첫 게시 시 이미 선언된 `0.1.0`을 사용할 수 있습니다.
+1. 버전 변경은 별도 PR로 검토합니다. `npm version patch --no-git-tag-version`(또는 `minor`/`major`)으로 `package.json`과 `package-lock.json`의 버전을 함께 올리고 main에 병합합니다.
 2. README의 개발 검사를 실행하고 `npm pack --dry-run`의 포함 파일을 확인합니다. `.env`, 키, 테스트 데이터가 없어야 하며 `dist`, Skill, README, LICENSE가 포함되어야 합니다. 실제 tarball을 별도 디렉터리에 설치해 CLI와 `setup`도 확인합니다.
 3. 통과한 main 커밋을 대상으로 `v<package.json 버전>` 태그의 안정 버전 GitHub Release를 게시합니다. CLI 예시:
 
    ```sh
-   gh release create v0.1.0 --repo velody-ai/steercards-agent-tools --target <검증한-main-커밋-SHA> --title v0.1.0 --generate-notes
+   gh release create v0.1.1 --repo velody-ai/steercards-agent-tools --target <검증한-main-커밋-SHA> --title v0.1.1 --generate-notes
    ```
 
    예시 버전과 SHA는 실제 릴리스에 맞춥니다. 초안 저장만으로는 게시하지 않으며 prerelease는 건너뜁니다. `latest` 외의 배포 태그는 현재 워크플로의 지원 범위에 없습니다.
@@ -38,6 +45,7 @@
 
 - OIDC 인증 오류: npm 설정의 저장소·workflow 파일명·`npm` 환경·직접 게시 권한을 확인합니다. GitHub-hosted runner와 npm 최소 버전도 확인합니다. 임시 해결용 토큰을 추가하지 않습니다.
 - 태그·버전 또는 main 포함 검사 실패: 릴리스가 가리키는 커밋과 버전 변경 PR을 확인합니다. 이미 게시된 npm 버전은 덮어쓰지 않습니다.
+- staged 버전은 직접 게시와 같은 버전 공간을 사용합니다. `0.1.0`을 stage한 상태에서 같은 버전을 직접 게시하면 `E409`가 발생했습니다. 최초 placeholder만 있는 패키지에서 마지막 stage를 reject하자 패키지가 레지스트리에서 조회되지 않고 OIDC 재시도는 `E404`로 실패했습니다([실행 기록](https://github.com/velody-ai/steercards-agent-tools/actions/runs/39330030138)). trusted publisher 설정의 삭제 여부는 이 결과만으로 판단하지 않습니다. 초기 설정에 stage → reject 절차를 사용하지 않습니다. 일반 최초 게시 후 패키지와 기존 trusted publisher 설정을 확인하고 필요한 설정을 진행합니다.
 - 게시 후 후속 단계가 실패했다면 먼저 `npm view`로 게시 여부를 확인합니다. 미게시일 때만 실패한 Actions 작업을 재실행합니다. 이미 게시된 버전에 다시 `npm publish`하면 오류가 납니다.
 
 근거: [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/), [npm provenance](https://docs.npmjs.com/generating-provenance-statements/), [npm trust 전제 조건](https://docs.npmjs.com/cli/v11/commands/npm-trust/).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@steercards/agent-tools",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Progressive MCP discovery, CLI and agent skills for Steercards",
   "type": "module",
   "license": "MIT",