@steercards/agent-tools 0.1.2 → 0.1.3

package/CONTRIBUTING.md

@@ -25,7 +25,7 @@ npm pack --dry-run
 - `serve`의 stdout은 MCP 메시지 전용입니다. 진단 로그는 stderr로 출력하고 키를 노출하지 않습니다.
 - `setup`은 MCP 설정과 Skill을 함께 설치·업데이트합니다. Steercards 외 설정·주석·사용자 파일은 보존하고 관리 항목에 사용자 수정이 있으면 쓰기 전에 중단합니다. 임시 프로젝트와 격리한 홈 디렉터리에서 첫 설치, 재실행, 이전 버전 업데이트, 충돌, dry run과 쓰기 실패 복구를 검증하세요.
 - `.steercards/setup/` 기록의 버전·옵션·해시를 다음 업데이트의 기준으로 사용합니다. 실제 개인 설치 기록과 ZIP은 테스트 fixture나 커밋에 넣지 마세요.
-- `setup`은 키 없이 실행하고 `.env`를 생성·변경하지 않습니다. `config`는 설정 조각만 출력하며 개별 `skill install`은 사용자 수정 파일을 덮어쓰지 않습니다.
+- 코드 옵션 없는 `setup`은 키 없이 실행하고 `.env`를 변경하지 않습니다. 일회용 코드 모드에서는 로컬 충돌·추적·쓰기 점검을 교환 전에 완료하고, 저장 뒤 설치 실패 시 `.env`를 보존합니다. HTTP fixture와 packed bin/npx·Windows stdin 검사에서 코드·키 비노출 및 재교환 금지를 확인하세요. `config`는 설정 조각만 출력하며 개별 `skill install`은 사용자 수정 파일을 덮어쓰지 않습니다.
 
 변경 제안은 [공개 저장소](https://github.com/velody-ai/steercards-agent-tools)에 PR로 올려주세요. 보안 문제는 공개 이슈에 올리지 말고 [SECURITY.md](SECURITY.md)를 따릅니다.
 

package/README.md

@@ -9,6 +9,34 @@ Steercards의 전체 MCP 도구를 CLI와 에이전트에서 사용할 수 있
 
 패키지 이름은 `@steercards/agent-tools`, 실행 명령은 `steercards`입니다. npm에서 설치하거나 소스에서 빌드해 사용할 수 있습니다.
 
+## 일회용 프롬프트로 연결
+
+Steercards의 Agent 연결 화면에서 클라이언트·OS·Key 설정을 선택하고 설치 프롬프트를 복사해 사용할 프로젝트의 에이전트에게 전달하세요. 프롬프트에는 10분 동안 한 번 사용할 설치 코드가 들어갑니다. 설치기는 코드를 실제 Agent Key로 교환하여 현재 프로젝트의 `.env`에만 저장하고, `.gitignore` 보호·MCP 설정·Skill 설치와 읽기 전용 연결 검사를 수행합니다. 장기 키를 프롬프트에 붙여넣을 필요가 없습니다.
+
+직접 실행하는 경우 아래 코드 자리를 앱에서 발급한 설치 코드로 바꿉니다. POSIX 셸 예시:
+
+```sh
+npx -y -- @steercards/agent-tools@latest setup --client codex-app --cwd . --env-file .env --url https://steercards.com/api/mcp --setup-code-stdin <<'STEERCARDS_SETUP_CODE'
+<일회용 설치 코드>
+STEERCARDS_SETUP_CODE
+```
+
+Windows PowerShell에서는 같은 코드를 here-string으로 전달합니다.
+
+```powershell
+@'
+<일회용 설치 코드>
+'@ | npx -y -- @steercards/agent-tools@latest setup --client codex-app --cwd . --env-file .env --url https://steercards.com/api/mcp --setup-code-stdin
+```
+
+`--cwd .`는 실행한 현재 프로젝트를 뜻하며 생략해도 같습니다. `--client`는 선택한 클라이언트로 바꾸고, 다른 서버를 사용한다면 그 서버의 MCP URL을 명시하세요. 설치 코드와 발급된 키는 명령 인자·출력·설치 기록에 넣지 않습니다. 자동 연결 검사는 호출 프로세스의 다른 키보다 저장한 `.env`의 키를 사용합니다.
+
+기존 `.env`의 다른 값·주석·개행을 보존합니다. 이미 Agent Key가 있으면 그대로 사용하고 코드를 교환하지 않습니다. 교체하려면 같은 setup 명령에 `--replace-agent-key`를 명시하세요. 이전 키를 서버에서 자동 폐기하지는 않습니다. 자동 쓰기는 프로젝트 루트 `.env`만 지원합니다. 이전 설치가 다른 env 파일을 참조하면 교환 전에 중단하므로 `--env-file .env`로 전환을 명시합니다.
+
+`.env`가 Git에 추적되거나 파일·설정·Skill 충돌, symlink, 잠금·쓰기 문제가 있으면 교환 전에 중단합니다. `.gitignore`의 기존 negation 뒤에 보호 규칙을 보완합니다. `--dry-run`은 코드를 소비하거나 파일을 쓰지 않습니다.
+
+키 저장 뒤 MCP·Skill 설치나 연결 검사에 실패해도 `.env`를 보존합니다. 충돌을 정리하고 코드 옵션 없이 일반 setup과 `doctor --connect`를 다시 실행하세요. 교환 응답 유실이나 키 저장 실패는 코드가 소비되었을 수 있으므로 앱에서 새 코드를 발급하고 사용하지 않는 발급 키를 폐기합니다. 실패 복구를 위해 키 원문을 채팅·로그에 붙여넣지 마세요. Desktop의 Skill ZIP 업로드와 클라이언트 재연결은 아래 안내를 따릅니다.
+
 ## 소스에서 설치
 
 소스 디렉터리에서 빌드한 뒤 `setup --local`을 실행합니다.
@@ -19,7 +47,7 @@ npm run build
 node -- /absolute/path/agent-tools/dist/cli.js setup --client codex-app --cwd /absolute/path/project --local
 ```
 
-`setup` 한 번으로 Steercards MCP 설정과 Skill을 함께 설치합니다. 키 없이 설치할 수 있으며 `.env`를 만들거나 덮어쓰지 않습니다. 설치 뒤 프로젝트에 `.env.example`을 참고한 `.env`를 만들고 실제 Agent Key를 입력하세요.
+코드 옵션 없는 `setup`은 Steercards MCP 설정과 Skill을 키 없이 설치하며 `.env`를 변경하지 않습니다. 수동 연결에서는 설치 뒤 프로젝트에 `.env.example`을 참고한 `.env`를 만들고 실제 Agent Key를 입력하세요.
 
 ```dotenv
 STEERCARDS_AGENT_KEY=your-agent-key
@@ -111,6 +139,7 @@ Claude Desktop 자동 설치는 macOS와 Windows를 지원합니다. MCP 설정
 
 ```sh
 steercards setup [--client CLIENT] [--local | --npx] [--dry-run] [--cwd PATH] [--env-file PATH] [--url URL] [--mode compact|full]
+  [--setup-code-stdin] [--replace-agent-key]
 ```
 
 `--dry-run`은 파일을 쓰지 않고 예정된 작업만 보여줍니다. 키를 출력하거나 연결 검사를 수행하지 않습니다. `setup`은 코드 클라이언트를 프로젝트 범위에 설치하며 `--global`을 지원하지 않습니다. `--env-file`, `--url`, `--mode`는 생성할 MCP 실행 옵션에도 반영됩니다. 같은 버전에서도 옵션을 바꾸면 해당 설정을 갱신합니다. `--local`과 `--npx`는 함께 사용할 수 없으며 `--npx`는 `setup` 전용 옵션입니다.

package/dist/cli.js

@@ -8,9 +8,11 @@ import { Runtime } from './runtime.js';
 import { startServer } from './server.js';
 import { clientConfig, installSkill, exportSkill, packageInfo } from './install.js';
 import { setup } from './setup.js';
+import { setupWithCode } from './setup-with-code.js';
 const help = `Steercards agent tools ${packageInfo.version}
 
 steercards setup [--client CLIENT] [--local | --npx] [--dry-run]
+  [--setup-code-stdin] [--replace-agent-key]
 steercards serve [--mode compact|full]
 steercards tools [query] [--limit 10]
 steercards describe NAME
@@ -28,6 +30,9 @@ setup installs MCP configuration and the skill together; rerun to update both.
 setup uses project scope (Desktop uses its user configuration and a project ZIP).
 --npx explicitly switches an existing local setup to a pinned npm package.
 --dry-run previews setup without writing files. No key is needed for setup.
+--setup-code-stdin reads a one-use installation code, protects the project .env,
+  installs MCP and the skill, then checks the connection. Existing keys are kept.
+--replace-agent-key explicitly replaces the project .env Agent Key.
 config only prints a snippet and never edits host settings.
 --local uses this installation's absolute Node/CLI paths (works before npm release).
 Claude Desktop: upload the skill ZIP, use compact get_guide, or full guide resources.
@@ -64,6 +69,18 @@ async function stdinText() {
     }
     return Buffer.concat(chunks).toString('utf8');
 }
+async function installationCode() {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of process.stdin) {
+        const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        size += bytes.length;
+        if (size > 1024)
+            throw new Error('Installation code input is too large.');
+        chunks.push(bytes);
+    }
+    return Buffer.concat(chunks).toString('utf8').replace(/\r?\n$/, '');
+}
 let secret = process.env.STEERCARDS_AGENT_KEY;
 async function main() {
     const { values, positionals } = parseArgs({ allowPositionals: true, strict: true, options: {
@@ -72,6 +89,7 @@ async function main() {
             client: { type: 'string' }, global: { type: 'boolean' }, output: { type: 'string' },
             limit: { type: 'string' }, connect: { type: 'boolean' }, local: { type: 'boolean' },
             'dry-run': { type: 'boolean' }, npx: { type: 'boolean' },
+            'setup-code-stdin': { type: 'boolean' }, 'replace-agent-key': { type: 'boolean' },
             help: { type: 'boolean', short: 'h' }, version: { type: 'boolean', short: 'v' },
         } });
     if (values.version) {
@@ -95,6 +113,8 @@ async function main() {
         }
         if (values.global)
             throw new Error('setup uses project scope; omit --global. Claude Desktop configuration is user-scoped.');
+        if (values['replace-agent-key'] && !values['setup-code-stdin'])
+            throw new Error('--replace-agent-key requires --setup-code-stdin.');
         if (values.local && values.npx)
             throw new Error('Choose only one of --local or --npx.');
         let client = values.client;
@@ -114,9 +134,21 @@ async function main() {
             if (!client)
                 throw new Error('No client selected. Nothing was installed.');
         }
-        output(await setup({ ...options, client, local: values.npx ? false : values.local, mode: values.mode, dryRun: values['dry-run'] }));
+        const setupOptions = { ...options, client, local: values.npx ? false : values.local, mode: values.mode, dryRun: values['dry-run'] };
+        if (values['setup-code-stdin']) {
+            const code = await installationCode();
+            secret = code;
+            const result = await setupWithCode({ ...setupOptions, code, replaceAgentKey: values['replace-agent-key'] });
+            output(result);
+            if (!result.ok)
+                process.exitCode = 1;
+        }
+        else
+            output(await setup(setupOptions));
         return;
     }
+    if (values['setup-code-stdin'] || values['replace-agent-key'])
+        throw new Error('Installation code options are only supported by setup.');
     if (values['dry-run'] || values.npx)
         throw new Error('--dry-run and --npx are only supported by setup.');
     if (command === 'config') {

package/dist/setup-credentials.d.ts

@@ -0,0 +1,22 @@
+export interface CredentialOptions {
+    cwd?: string;
+    envFile?: string;
+    savedEnvFile?: string;
+    replaceAgentKey?: boolean;
+    dryRun?: boolean;
+}
+/** Holds only nonsecret metadata in enumerable properties. */
+export interface ProjectCredentials {
+    cwd: string;
+    envFile: string;
+    needsExchange: boolean;
+    actions: string[];
+    verify(): Promise<void>;
+    protect(): Promise<void>;
+    save(token: string): Promise<void>;
+    readKey(): Promise<string>;
+    readMcpUrl(): Promise<string | undefined>;
+    close(): Promise<void>;
+}
+/** Preflight local credentials while holding a project lock shared by every client. */
+export declare function prepareProjectCredentials(options?: CredentialOptions): Promise<ProjectCredentials>;

package/dist/setup-credentials.js

@@ -0,0 +1,326 @@
+import { randomUUID } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { lstat, mkdir, open, readFile, realpath, rename, rm, rmdir } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { parse } from 'dotenv';
+const exec = promisify(execFile);
+const keyName = 'STEERCARDS_AGENT_KEY';
+const keyPattern = /^sc_agent_[A-Za-z0-9_-]{43}$/;
+const missing = (error) => error.code === 'ENOENT';
+async function noSymlink(path) {
+    let current = path;
+    while (true) {
+        try {
+            if ((await lstat(current)).isSymbolicLink())
+                throw new Error('Setup refuses a symbolic link in a credential path.');
+        }
+        catch (error) {
+            if (!missing(error))
+                throw error;
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            return;
+        current = parent;
+    }
+}
+async function snapshot(path) {
+    await noSymlink(path);
+    try {
+        const stat = await lstat(path);
+        if (!stat.isFile() || stat.nlink !== 1)
+            throw new Error('Credential and ignore files must be ordinary, unlinked files.');
+        if (stat.size > 1024 * 1024)
+            throw new Error('Credential or ignore file is too large to update safely.');
+        const bytes = await readFile(path);
+        try {
+            new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+        }
+        catch {
+            throw new Error('Credential and ignore files must use UTF-8.');
+        }
+        return bytes;
+    }
+    catch (error) {
+        if (missing(error))
+            return null;
+        throw error;
+    }
+}
+const same = (left, right) => left === null ? right === null : right !== null && left.equals(right);
+const eol = (text) => text.includes('\r\n') ? '\r\n' : '\n';
+/** Locate assignments without mistaking lines inside another multiline value for keys. */
+function keyValue(text) {
+    const assignments = [];
+    let offset = text.charCodeAt(0) === 0xfeff ? 1 : 0;
+    while (offset < text.length) {
+        const lineEnd = text.indexOf('\n', offset);
+        const end = lineEnd < 0 ? text.length : lineEnd;
+        const line = text.slice(offset, end).replace(/\r$/, '');
+        const match = /^([ \t]*(?:export[ \t]+)?([\w.-]+)[ \t]*(?:=[ \t]*|:[ \t]+))(.*)$/.exec(line);
+        if (!match) {
+            offset = lineEnd < 0 ? text.length : lineEnd + 1;
+            continue;
+        }
+        const start = offset + match[1].length;
+        let valueEnd = start;
+        const quote = text[start];
+        if (["'", '"', '`'].includes(quote)) {
+            valueEnd = start + 1;
+            let closed = false;
+            for (; valueEnd < text.length; valueEnd++) {
+                if (text[valueEnd] !== quote)
+                    continue;
+                let slashes = 0;
+                for (let i = valueEnd - 1; i > start && text[i] === '\\'; i--)
+                    slashes++;
+                if (slashes % 2 === 0) {
+                    valueEnd++;
+                    closed = true;
+                    break;
+                }
+            }
+            if (!closed)
+                throw new Error('Environment file contains an unterminated quoted value. Review it before setup.');
+            const tailEnd = text.indexOf('\n', valueEnd);
+            const tail = text.slice(valueEnd, tailEnd < 0 ? text.length : tailEnd).replace(/\r$/, '');
+            if (!/^[ \t]*(?:#.*)?$/.test(tail))
+                throw new Error('Environment file contains an ambiguous quoted assignment. Review it before setup.');
+            offset = tailEnd < 0 ? text.length : tailEnd + 1;
+        }
+        else {
+            const comment = match[3].indexOf('#');
+            valueEnd = start + (comment < 0 ? match[3] : match[3].slice(0, comment)).trimEnd().length;
+            offset = lineEnd < 0 ? text.length : lineEnd + 1;
+        }
+        if (match[2] === keyName) {
+            if (/[\r\n]/.test(text.slice(start, valueEnd)))
+                throw new Error('A multiline Agent Key assignment cannot be replaced automatically.');
+            const value = parse(`${keyName}=${text.slice(start, valueEnd)}`)[keyName] ?? '';
+            if (/\s/.test(value))
+                throw new Error('The existing Agent Key is invalid. Review its environment assignment before setup.');
+            assignments.push({ start, end: valueEnd, value });
+        }
+    }
+    if (assignments.length > 1)
+        throw new Error('Environment file contains duplicate Agent Key assignments. Resolve them before setup.');
+    return assignments[0];
+}
+function withKey(text, token) {
+    const assignment = keyValue(text);
+    if (assignment)
+        return text.slice(0, assignment.start) + token + text.slice(assignment.end);
+    return text + (text && !text.endsWith('\n') ? eol(text) : '') + `${keyName}=${token}${eol(text)}`;
+}
+function withIgnore(text) {
+    const patterns = text.replace(/^\uFEFF/, '').split(/\r?\n/).map(line => line.trimEnd()).filter(line => line && !line.startsWith('#'));
+    if (patterns.at(-2) === '/.env' && patterns.at(-1) === '/.steercards/')
+        return text;
+    const newline = eol(text);
+    return text + (text && !text.endsWith('\n') ? newline : '') + `# Steercards local credentials${newline}/.env${newline}/.steercards/${newline}`;
+}
+/** Git's index takes precedence over ignore rules; never put a new secret in a tracked file. */
+async function assertUntracked(cwd) {
+    let current = cwd;
+    let repository = false;
+    while (true) {
+        try {
+            await lstat(join(current, '.git'));
+            repository = true;
+            break;
+        }
+        catch (error) {
+            if (!missing(error))
+                throw new Error('Unable to inspect Git tracking before setup.');
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    if (!repository)
+        return;
+    const env = Object.fromEntries(Object.entries(process.env).filter(([name]) => !name.startsWith('GIT_')));
+    let output;
+    try {
+        ({ stdout: output } = await exec('git', ['-C', cwd, 'ls-files', '-z', '--', ':(icase,literal).env'], { env, timeout: 10000, maxBuffer: 64 * 1024 }));
+    }
+    catch {
+        throw new Error('Unable to verify Git tracking. Install Git or resolve the repository error before setup.');
+    }
+    if (output)
+        throw new Error('The project .env is tracked by Git. Stop tracking it yourself before installing credentials.');
+}
+async function atomicWrite(path, bytes, mode = 0o600) {
+    await noSymlink(path);
+    const stage = join(dirname(path), `.steercards-${randomUUID()}.tmp`);
+    try {
+        const file = await open(stage, 'wx', mode);
+        try {
+            await file.writeFile(bytes);
+            await file.sync();
+        }
+        finally {
+            await file.close();
+        }
+        await rename(stage, path);
+    }
+    finally {
+        await rm(stage, { force: true });
+    }
+}
+/** Preflight local credentials while holding a project lock shared by every client. */
+export async function prepareProjectCredentials(options = {}) {
+    let cwd;
+    try {
+        cwd = await realpath(resolve(options.cwd ?? process.cwd()));
+        if (!(await lstat(cwd)).isDirectory())
+            throw new Error();
+    }
+    catch {
+        throw new Error('The selected project directory must already exist.');
+    }
+    const envFile = join(cwd, '.env');
+    if (options.envFile !== undefined && resolve(cwd, options.envFile) !== envFile)
+        throw new Error('Automatic credentials only support the project .env. Use --env-file .env.');
+    if (options.envFile === undefined && options.savedEnvFile !== undefined && resolve(cwd, options.savedEnvFile) !== envFile)
+        throw new Error('This installation uses another environment file. Explicitly select --env-file .env to switch before redeeming a code.');
+    const ignoreFile = join(cwd, '.gitignore');
+    const lockPath = join(cwd, '.steercards', 'setup', 'credentials.lock');
+    const created = [];
+    let locked = false;
+    let closed = false;
+    const lockBytes = Buffer.from(`${process.pid}:${randomUUID()}\n`);
+    const ensureDirectory = async (path) => {
+        await noSymlink(path);
+        try {
+            if (!(await lstat(path)).isDirectory())
+                throw new Error('Expected a setup directory.');
+            return;
+        }
+        catch (error) {
+            if (!missing(error))
+                throw error;
+        }
+        await ensureDirectory(dirname(path));
+        try {
+            await mkdir(path, { mode: 0o700 });
+            created.push(path);
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            await noSymlink(path);
+            if (!(await lstat(path)).isDirectory())
+                throw new Error('Expected a setup directory.');
+        }
+    };
+    const close = async () => {
+        if (closed)
+            return;
+        closed = true;
+        if (locked && same(lockBytes, await snapshot(lockPath)))
+            await rm(lockPath);
+        for (const path of created.reverse()) {
+            try {
+                await rmdir(path);
+            }
+            catch (error) {
+                if (!missing(error) && !['ENOTEMPTY', 'EEXIST'].includes(error.code ?? ''))
+                    throw error;
+            }
+        }
+    };
+    try {
+        await noSymlink(lockPath);
+        if (!options.dryRun) {
+            await ensureDirectory(dirname(lockPath));
+            try {
+                const file = await open(lockPath, 'wx', 0o600);
+                locked = true;
+                try {
+                    await file.writeFile(lockBytes);
+                }
+                finally {
+                    await file.close();
+                }
+            }
+            catch (error) {
+                if (error.code === 'EEXIST')
+                    throw new Error('Another setup holds the project credential lock. Wait for it to finish.');
+                throw new Error('Unable to acquire the project credential lock. Check directory permissions.');
+            }
+        }
+        let envBefore = await snapshot(envFile);
+        let ignoreBefore = await snapshot(ignoreFile);
+        const existing = keyValue(envBefore?.toString('utf8') ?? '')?.value;
+        const needsExchange = !existing || options.replaceAgentKey === true;
+        const ignoreAfter = Buffer.from(withIgnore(ignoreBefore?.toString('utf8') ?? ''));
+        const ignoreMode = ignoreBefore ? (await lstat(ignoreFile)).mode & 0o777 : 0o644;
+        if (needsExchange && envBefore && ((await lstat(envFile)).mode & 0o200) === 0)
+            throw new Error('The project environment file is read-only. Change its permissions before setup.');
+        if (!same(ignoreBefore, ignoreAfter) && ignoreBefore && (ignoreMode & 0o200) === 0)
+            throw new Error('The project ignore file is read-only. Change its permissions before setup.');
+        await assertUntracked(cwd);
+        const verify = async () => {
+            if (closed)
+                throw new Error('Credential setup is already closed.');
+            await assertUntracked(cwd);
+            if (!same(envBefore, await snapshot(envFile)) || !same(ignoreBefore, await snapshot(ignoreFile)))
+                throw new Error('The project environment or ignore file changed during setup. Review it and retry.');
+        };
+        if (!options.dryRun && (needsExchange || !same(ignoreBefore, ignoreAfter))) {
+            // A real same-directory create/rename probe catches permissions before consuming a code.
+            const probe = join(cwd, `.steercards-probe-${randomUUID()}.tmp`);
+            try {
+                await atomicWrite(probe, Buffer.alloc(0));
+            }
+            catch {
+                throw new Error('The project directory does not allow safe credential writes.');
+            }
+            finally {
+                await rm(probe, { force: true });
+            }
+        }
+        const actions = [...(!same(ignoreBefore, ignoreAfter) ? ['protect project .env and .steercards in .gitignore'] : []), ...(needsExchange ? [existing ? 'replace project Agent Key' : 'save project Agent Key'] : ['keep existing project Agent Key'])];
+        return {
+            cwd, envFile, needsExchange, actions, verify, close,
+            async protect() {
+                if (options.dryRun)
+                    throw new Error('A dry run cannot write files.');
+                await verify();
+                if (!same(ignoreBefore, ignoreAfter)) {
+                    await atomicWrite(ignoreFile, ignoreAfter, ignoreMode);
+                    ignoreBefore = ignoreAfter;
+                }
+            },
+            async save(token) {
+                if (options.dryRun)
+                    throw new Error('A dry run cannot save credentials.');
+                if (!needsExchange)
+                    throw new Error('The existing project Agent Key must be preserved.');
+                if (!keyPattern.test(token))
+                    throw new Error('The exchanged Agent Key has an invalid format.');
+                await verify();
+                if (!same(ignoreBefore, ignoreAfter))
+                    throw new Error('Protect the project environment file before saving credentials.');
+                const bytes = Buffer.from(withKey(envBefore?.toString('utf8') ?? '', token));
+                await atomicWrite(envFile, bytes);
+                envBefore = bytes;
+            },
+            async readKey() {
+                await verify();
+                const value = keyValue(envBefore?.toString('utf8') ?? '')?.value;
+                if (!value)
+                    throw new Error('The project environment file has no Agent Key.');
+                return value;
+            },
+            async readMcpUrl() { await verify(); return parse(envBefore?.toString('utf8') ?? '').STEERCARDS_MCP_URL; },
+        };
+    }
+    catch (error) {
+        await close();
+        throw error;
+    }
+}

package/dist/setup-with-code.d.ts

@@ -0,0 +1,40 @@
+import { type SetupOptions, type SetupReport, type SetupDependencies } from './setup.js';
+export declare const INSTALL_CODE_PATTERN: RegExp;
+type Receipt = {
+    installationId: string;
+    keyId: string;
+    profileIds: string[];
+};
+export interface CodeSetupReport {
+    ok: boolean;
+    setup: SetupReport | null;
+    credentials: {
+        status: 'not-saved' | 'saved' | 'kept' | 'dry-run';
+        envFile?: string;
+    };
+    doctor: {
+        connected: boolean | null;
+        keySource?: 'env-file';
+        toolCount?: number;
+    };
+    receipt?: Receipt;
+    error?: string;
+    nextSteps: string[];
+}
+export interface CodeSetupOptions extends SetupOptions {
+    code: string;
+    replaceAgentKey?: boolean;
+}
+/** Isolated HTTP, filesystem failure and diagnostic fixtures; never needed by normal callers. */
+export interface CodeSetupDependencies {
+    fetch?: typeof fetch;
+    setup?: SetupDependencies;
+    doctor?: (cwd: string, url: string) => Promise<{
+        connected: boolean;
+        keySource: 'env-file';
+        toolCount?: number;
+    }>;
+}
+/** Redeem only after local setup is ready; keep saved credentials if later configuration fails. */
+export declare function setupWithCode(options: CodeSetupOptions, dependencies?: CodeSetupDependencies): Promise<CodeSetupReport>;
+export {};

package/dist/setup-with-code.js

@@ -0,0 +1,196 @@
+import { DEFAULT_MCP_URL, loadConfig, validateMcpUrl } from './config.js';
+import { Runtime } from './runtime.js';
+import { setup } from './setup.js';
+import { prepareProjectCredentials } from './setup-credentials.js';
+import { realpath, stat } from 'node:fs/promises';
+import { resolve } from 'node:path';
+export const INSTALL_CODE_PATTERN = /^sc_install_[A-Za-z0-9_-]{43}$/;
+const tokenPattern = /^sc_agent_[A-Za-z0-9_-]{43}$/;
+const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const errors = {
+    AGENT_INSTALL_CODE_NOT_FOUND: 'Installation code was not found. Create a new code in Steercards.',
+    AGENT_INSTALL_CODE_EXPIRED: 'Installation code expired. Create a new code in Steercards.',
+    AGENT_INSTALL_CODE_REVOKED: 'Installation code was revoked. Create a new code in Steercards.',
+    AGENT_INSTALL_CODE_CONSUMED: 'Installation code was already used. Check the issued Agent Key in Steercards before creating a new code.',
+    AGENT_INSTALL_CODE_PROFILE_INVALID: 'The selected profiles are no longer available. Create a new installation code.',
+    AGENT_INSTALL_CODE_OWNER_INVALID: 'The installation owner is no longer available. Sign in to Steercards and create a new code.',
+    RATE_LIMITED: 'Too many installation attempts. Wait before creating another request.',
+};
+const recovery = 'The code may have been consumed. Create a new code and remove any unused issued Agent Key in Steercards. Never paste the Agent Key into chat.';
+async function boundedJson(response) {
+    if (!response.headers.get('content-type')?.toLowerCase().includes('application/json')) {
+        await response.body?.cancel();
+        throw new Error('Installation service returned an invalid response.');
+    }
+    const reader = response.body?.getReader();
+    if (!reader)
+        throw new Error('Installation service returned an empty response.');
+    let size = 0;
+    const chunks = [];
+    try {
+        while (true) {
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            size += value.byteLength;
+            if (size > 64 * 1024) {
+                await reader.cancel();
+                throw new Error('Installation service response is too large.');
+            }
+            chunks.push(value);
+        }
+        try {
+            return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+        }
+        catch {
+            throw new Error('Installation service returned invalid JSON.');
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+async function exchange(code, url, fetcher) {
+    let response;
+    try {
+        response = await fetcher(new URL('/api/agent-setup/exchange', url), {
+            method: 'POST', headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+            body: JSON.stringify({ code }), redirect: 'error', signal: AbortSignal.timeout(15000),
+        });
+    }
+    catch {
+        throw new Error(`Unable to confirm installation code exchange. ${recovery}`);
+    }
+    let value;
+    try {
+        value = await boundedJson(response);
+    }
+    catch {
+        throw new Error(`Installation service returned an invalid or incomplete response. ${recovery}`);
+    }
+    if (!response.ok) {
+        const errorCode = value?.error?.code;
+        const message = typeof errorCode === 'string' && Object.hasOwn(errors, errorCode) ? errors[errorCode] : undefined;
+        throw new Error(message ?? `Installation service rejected the request (HTTP ${response.status}). ${recovery}`);
+    }
+    if (!value || typeof value.token !== 'string' || !tokenPattern.test(value.token)
+        || typeof value.installationId !== 'string' || !uuidPattern.test(value.installationId)
+        || !value.key || typeof value.key.id !== 'string' || !uuidPattern.test(value.key.id) || !Array.isArray(value.profileIds)
+        || value.profileIds.length > 30 || value.profileIds.some((id) => typeof id !== 'string' || !uuidPattern.test(id))
+        || new Set(value.profileIds).size !== value.profileIds.length)
+        throw new Error(`Installation service returned invalid credentials. ${recovery}`);
+    return { token: value.token, receipt: { installationId: value.installationId, keyId: value.key.id, profileIds: value.profileIds } };
+}
+async function doctor(cwd, url) {
+    // Explicitly inspect the stored file, regardless of the invoking agent's environment.
+    const config = await loadConfig({ cwd, envFile: '.env', url, env: {} });
+    const runtime = new Runtime(config);
+    const timeout = setTimeout(() => { void runtime.close().catch(() => { }); }, 15000);
+    timeout.unref();
+    try {
+        const tools = await runtime.listTools();
+        const result = await runtime.callTool('list_workspaces', {});
+        let failed = result.isError === true || result.structuredContent?.ok === false;
+        for (const item of result.content)
+            if (item.type === 'text') {
+                try {
+                    if (JSON.parse(item.text)?.ok === false)
+                        failed = true;
+                }
+                catch { /* Ordinary text is allowed. */ }
+            }
+        return { connected: !failed, keySource: 'env-file', toolCount: tools.length };
+    }
+    finally {
+        clearTimeout(timeout);
+        await runtime.close();
+    }
+}
+/** Redeem only after local setup is ready; keep saved credentials if later configuration fails. */
+export async function setupWithCode(options, dependencies = {}) {
+    const report = { ok: false, setup: null, credentials: { status: 'not-saved' }, doctor: { connected: null }, nextSteps: [] };
+    let credentials;
+    let token;
+    let attemptedExchange = false;
+    let mcpUrl;
+    try {
+        if (!INSTALL_CODE_PATTERN.test(options.code))
+            throw new Error('Installation code has an invalid format. Copy a fresh setup prompt from Steercards.');
+        try {
+            if (!(await stat(await realpath(resolve(options.cwd ?? process.cwd())))).isDirectory())
+                throw new Error();
+        }
+        catch {
+            throw new Error('The selected project directory must already exist.');
+        }
+        mcpUrl = validateMcpUrl(options.url ?? DEFAULT_MCP_URL);
+        report.setup = await setup({ ...options, url: mcpUrl }, {
+            ...dependencies.setup,
+            async afterPreflight(context) {
+                credentials = await prepareProjectCredentials({ cwd: context.cwd, envFile: options.envFile, savedEnvFile: context.envFile, replaceAgentKey: options.replaceAgentKey, dryRun: context.dryRun });
+                report.credentials.envFile = credentials.envFile;
+                const savedUrl = await credentials.readMcpUrl();
+                if (savedUrl && new URL(validateMcpUrl(savedUrl)).origin !== new URL(mcpUrl).origin && options.url === undefined)
+                    throw new Error('The project uses another MCP server. Explicitly select its --url before redeeming an installation code.');
+                if (context.dryRun) {
+                    report.credentials.status = 'dry-run';
+                    return;
+                }
+                await credentials.protect();
+                if (!credentials.needsExchange) {
+                    report.credentials.status = 'kept';
+                    return;
+                }
+                await credentials.verify();
+                attemptedExchange = true;
+                const claimed = await exchange(options.code, mcpUrl, dependencies.fetch ?? fetch);
+                token = claimed.token;
+                report.receipt = claimed.receipt;
+                try {
+                    await credentials.save(token);
+                }
+                catch {
+                    throw new Error(`The issued Agent Key could not be saved safely. ${recovery}`);
+                }
+                report.credentials.status = 'saved';
+            },
+        });
+        report.setup.actions.unshift(...credentials.actions);
+        report.setup.nextSteps = report.setup.nextSteps.filter(step => !step.startsWith('Set STEERCARDS_AGENT_KEY'));
+        if (options.dryRun) {
+            report.ok = true;
+            report.nextSteps = ['Run setup again without --dry-run to complete installation.'];
+            return report;
+        }
+        try {
+            report.doctor = await (dependencies.doctor ?? doctor)(credentials.cwd, mcpUrl);
+        }
+        catch {
+            report.doctor = { connected: false, keySource: 'env-file' };
+        }
+        report.ok = report.doctor.connected === true;
+        report.nextSteps = [...report.setup.nextSteps, ...(!report.ok ? ['Credentials and setup were preserved. Run doctor --connect after checking the MCP server. Do not redeem the code again.'] : [])];
+        if (!report.ok)
+            report.error = 'Setup completed, but the connection check did not succeed.';
+    }
+    catch (error) {
+        let message = error instanceof Error ? error.message : 'Installation failed.';
+        for (const secret of [options.code, token])
+            if (secret)
+                message = message.split(secret).join('[REDACTED]');
+        report.error = message;
+        report.nextSteps = report.credentials.status === 'saved' || report.credentials.status === 'kept'
+            ? ['The project .env was preserved. Fix the configuration conflict and rerun setup without an installation code, then doctor --connect.']
+            : [attemptedExchange ? recovery : 'Resolve the local setup issue and rerun the prompt before the code expires.'];
+    }
+    finally {
+        try {
+            await credentials?.close();
+        }
+        catch {
+            report.ok = false;
+            report.error = 'Setup could not release its local lock. Review the project setup lock before retrying.';
+        }
+    }
+    return report;
+}

package/dist/setup.d.ts

@@ -29,6 +29,12 @@ export interface SetupDependencies {
     version?: string;
     beforeCommit?: () => Promise<void>;
     beforeWrite?: (path: string, index: number) => Promise<void>;
+    /** Runs under the config lock after all destinations are checked; dry runs never redeem codes. */
+    afterPreflight?: (context: {
+        cwd: string;
+        envFile?: string;
+        dryRun: boolean;
+    }) => Promise<void>;
 }
 /** Configure MCP and the matching skill together, preserving unrelated client data. */
 export declare function setup(options: SetupOptions, dependencies?: SetupDependencies): Promise<SetupReport>;

package/dist/setup.js

@@ -349,7 +349,11 @@ export async function setup(options, dependencies = {}) {
         ? [`Restart Claude Desktop to load the MCP server.`, `Upload ${zipPath} in Claude's skill settings. Repeat the upload after a skill update.`, 'Set STEERCARDS_AGENT_KEY in the project .env or the referenced env file before using MCP.']
         : ['Restart or reload your client to load the MCP server and skill.', 'Set STEERCARDS_AGENT_KEY in the project .env or the referenced env file before using MCP.'];
     const report = { client, version, status: options.dryRun ? 'dry-run' : plan.size ? previous ? 'updated' : 'installed' : 'unchanged', paths, actions, nextSteps };
-    if (options.dryRun || !plan.size)
+    if (options.dryRun) {
+        await dependencies.afterPreflight?.({ cwd, envFile: effective.envFile, dryRun: true });
+        return report;
+    }
+    if (!plan.size && !dependencies.afterPreflight)
         return report;
     // This is an ordinary-failure transaction, not a crash-atomic multi-file commit.
     const createdDirectories = [];
@@ -398,6 +402,29 @@ export async function setup(options, dependencies = {}) {
         }
         if (skillPath)
             await checkSkillTree(skillPath);
+        if (dependencies.afterPreflight) {
+            // Exercise destination directories before a one-use credential is consumed.
+            for (const parent of new Set([...plan.keys()].map(path => dirname(path)))) {
+                await ensureDirectory(parent);
+                const probe = join(parent, `.steercards-write-probe-${randomUUID()}.tmp`);
+                try {
+                    await atomicWrite(probe, Buffer.alloc(0), 0o600, ensureDirectory);
+                }
+                catch {
+                    throw new Error('A setup destination does not allow safe writes. Check its directory permissions.');
+                }
+                finally {
+                    await rm(probe, { force: true });
+                }
+            }
+            for (const [path, before] of baselines) {
+                if (!sameSnapshot(before, await snapshot(path)))
+                    throw new Error('A setup destination changed during preflight. No credential was requested.');
+                if (plan.has(path) && before && (before.mode & 0o200) === 0)
+                    throw new Error('A setup destination is read-only. Change its permissions before installing credentials.');
+            }
+            await dependencies.afterPreflight({ cwd, envFile: effective.envFile, dryRun: false });
+        }
         let index = 0;
         for (const [path, bytes] of plan) {
             await dependencies.beforeWrite?.(path, index++);

package/package.json

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

package/skills/steercards/SKILL.md

@@ -7,6 +7,12 @@ description: Manage Steercards workspaces, boards, cards, files and agent collab
 
 Use the connected Steercards toolkit MCP or its `steercards` CLI. Authentication comes from `STEERCARDS_AGENT_KEY`, including a local dotenv file configured for the toolkit. Keep credentials out of tool arguments, logs and committed files. GUI hosts can use an absolute env-file path; their working directory may differ from the project.
 
+## Connecting from an installation prompt
+
+When the user provides a Steercards installation prompt, run its `setup --setup-code-stdin` command in the intended project with `--cwd . --env-file .env` and the prompt's explicit MCP `--url`. Pass the short-lived code through stdin. The installer exchanges it once, saves the Agent Key only in the project `.env`, protects Git ignore rules, installs MCP and this skill, and checks the connection. Report the safe installation summary; never print the resulting key or inspect the exchange body for chat output.
+
+An existing project key is kept without consuming the code. Replace it only when requested, using `--replace-agent-key`. Automatic credential writes support only the project root `.env`. Local configuration/skill conflicts or a tracked `.env` must be resolved before redeeming. If credentials were saved but installation or doctor failed, preserve `.env` and rerun normal setup/doctor without a code. After an uncertain exchange or failed key save, ask for a fresh app-generated prompt and direct the user to remove unused issued keys in Steercards; do not replay the code or request the long-lived key in chat. Client restart/reconnect and Desktop Skill ZIP upload may still be needed.
+
 ## Discover only what the task needs
 
 1. Search capabilities: `steercards_search_tools({query: "card context", limit: 5})`.