apiskill 0.1.4 → 0.1.5

package/README.md

@@ -17,7 +17,7 @@ npm install -g apiskill
 apiskill run web
 ```
 
-Global npm installations store version data in the user-writable `~/.apiskill/cache` directory by default. Use `--cwd` for a project-local `<cwd>/cache`, or `--cache-dir` for a custom location. When developing this repository, you can also start it from the project root:
+Web, CLI, and MCP all use the same user-writable `~/.apiskill/cache` directory by default. `--cwd` only changes the Web process working directory and never changes this shared cache. For an isolated cache, set the same absolute `APISKILL_CACHE_DIR` for every Web, CLI, and MCP process. When developing this repository, you can also start it from the project root:
 
 ```bash
 npm install

package/README.zh.md

@@ -17,7 +17,7 @@ npm install -g apiskill
 apiskill run web
 ```
 
-通过 npm 全局安装时，Web 端默认使用用户可写的 `~/.apiskill/cache` 保存版本数据。使用 `--cwd` 可切换为项目目录下的 `<cwd>/cache`，使用 `--cache-dir` 可指定其他位置。开发本仓库时也可以在项目根目录启动：
+Web、CLI 和 MCP 默认统一使用用户可写的 `~/.apiskill/cache`，共同读写同一份文档和版本。`--cwd` 只改变 Web 进程的工作目录，不再改变共享缓存。需要隔离缓存时，必须为 Web、CLI 和 MCP 设置完全相同的绝对路径 `APISKILL_CACHE_DIR`。开发本仓库时也可以在项目根目录启动：
 
 ```bash
 npm install

package/docs/cli.md

@@ -14,11 +14,12 @@ apiskill --help
 apiskill run web
 ```
 
-`apiskill run web` starts the web console and writes cache data to the user-writable `~/.apiskill/cache` directory by default. `--cwd` uses `<cwd>/cache`; `--cache-dir` selects an explicit location:
+`apiskill run web`, CLI commands, and MCP all use `~/.apiskill/cache` by default. `--cwd` changes only the Web working directory and does not change the shared cache. For project isolation, set the same absolute `APISKILL_CACHE_DIR` for every Web, CLI, and MCP process:
 
 ```bash
 apiskill run web --port 8890
-apiskill run web --cwd /path/to/project --cache-dir .apiskill-cache
+APISKILL_CACHE_DIR=/path/to/project/.apiskill-cache apiskill run web --cwd /path/to/project
+APISKILL_CACHE_DIR=/path/to/project/.apiskill-cache apiskill check --json
 ```
 
 From the source project root:

package/docs/cli.zh.md

@@ -14,11 +14,12 @@ apiskill --help
 apiskill run web
 ```
 
-`apiskill run web` 会启动 Web 控制台，默认把缓存写入用户可写的 `~/.apiskill/cache`。使用 `--cwd` 时缓存位于 `<cwd>/cache`，也可以用 `--cache-dir` 指定其他目录：
+`apiskill run web`、其他 CLI 命令和 MCP 默认统一使用 `~/.apiskill/cache`。`--cwd` 只改变 Web 工作目录，不会改变共享缓存。需要按项目隔离时，必须为 Web、CLI 和 MCP 设置相同的绝对路径 `APISKILL_CACHE_DIR`：
 
 ```bash
 apiskill run web --port 8890
-apiskill run web --cwd /path/to/project --cache-dir .apiskill-cache
+APISKILL_CACHE_DIR=/path/to/project/.apiskill-cache apiskill run web --cwd /path/to/project
+APISKILL_CACHE_DIR=/path/to/project/.apiskill-cache apiskill check --json
 ```
 
 在源码项目根目录运行：

package/docs/mcp.ja.md

@@ -20,12 +20,10 @@ cwd = "/Users/dobby/dev/apiskill"
 startup_timeout_sec = 10
 tool_timeout_sec = 60
 enabled = true
-
-[mcp_servers.apiskill.env]
-APISKILL_ROOT = "/Users/dobby/dev/apiskill"
-APISKILL_CACHE_DIR = "/Users/dobby/dev/apiskill/cache"
 ```
 
+キャッシュ環境変数を設定しない場合、MCP、Web、CLI は同じ `~/.apiskill/cache` を使用します。プロジェクトごとに分離する場合は、3 つのプロセスすべてに同じ絶対パスの `APISKILL_CACHE_DIR` を設定してください。
+
 Codex を再起動して `/mcp` を実行します。`apiskill` と以下のツールが表示されるはずです。
 
 ## 読み取りツール

package/docs/mcp.ko.md

@@ -20,12 +20,10 @@ cwd = "/Users/dobby/dev/apiskill"
 startup_timeout_sec = 10
 tool_timeout_sec = 60
 enabled = true
-
-[mcp_servers.apiskill.env]
-APISKILL_ROOT = "/Users/dobby/dev/apiskill"
-APISKILL_CACHE_DIR = "/Users/dobby/dev/apiskill/cache"
 ```
 
+캐시 환경 변수를 설정하지 않으면 MCP, Web, CLI는 모두 같은 `~/.apiskill/cache`를 사용합니다. 프로젝트별로 분리할 때는 세 프로세스에 동일한 절대 경로의 `APISKILL_CACHE_DIR`를 설정하세요.
+
 Codex를 재시작하고 `/mcp`를 실행합니다. `apiskill`과 아래 도구들이 보여야 합니다.
 
 ## 읽기 도구

package/docs/mcp.md

@@ -22,12 +22,10 @@ cwd = "/Users/dobby/dev/apiskill"
 startup_timeout_sec = 10
 tool_timeout_sec = 60
 enabled = true
-
-[mcp_servers.apiskill.env]
-APISKILL_ROOT = "/Users/dobby/dev/apiskill"
-APISKILL_CACHE_DIR = "/Users/dobby/dev/apiskill/cache"
 ```
 
+With no cache environment configured, MCP uses the same `~/.apiskill/cache` default as Web and CLI. For project isolation, set one absolute `APISKILL_CACHE_DIR` value and use that exact value for all three processes.
+
 Restart Codex and run `/mcp`. You should see `apiskill` with the tools below.
 
 ## Read Tools

package/docs/mcp.zh.md

@@ -22,12 +22,10 @@ cwd = "/Users/dobby/dev/apiskill"
 startup_timeout_sec = 10
 tool_timeout_sec = 60
 enabled = true
-
-[mcp_servers.apiskill.env]
-APISKILL_ROOT = "/Users/dobby/dev/apiskill"
-APISKILL_CACHE_DIR = "/Users/dobby/dev/apiskill/cache"
 ```
 
+不配置缓存环境变量时，MCP 与 Web、CLI 一样默认使用 `~/.apiskill/cache`。需要按项目隔离时，设置一个绝对路径 `APISKILL_CACHE_DIR`，并确保三个进程使用完全相同的值。
+
 重启 Codex 后运行 `/mcp`，应该能看到 `apiskill` 和下面的工具。
 
 ## 只读工具

package/docs/web.md

@@ -11,7 +11,7 @@ npm install -g apiskill
 apiskill run web
 ```
 
-Global npm installations use the user-writable `~/.apiskill/cache` directory by default. Use `--cwd` for a project-local `<cwd>/cache`, or `--cache-dir` for an explicit path. When developing this repository, you can also use:
+Web, CLI, and MCP use the same user-writable `~/.apiskill/cache` directory by default. `--cwd` changes only the working directory. For an isolated cache, set the same absolute `APISKILL_CACHE_DIR` for all three processes. When developing this repository, you can also use:
 
 ```bash
 npm install

package/docs/web.zh.md

@@ -11,7 +11,7 @@ npm install -g apiskill
 apiskill run web
 ```
 
-通过 npm 全局安装时，默认缓存目录是用户可写的 `~/.apiskill/cache`。使用 `--cwd` 可切换为项目目录下的 `<cwd>/cache`，使用 `--cache-dir` 可指定其他位置。开发本仓库时也可以使用：
+Web、CLI 和 MCP 默认统一使用用户可写的 `~/.apiskill/cache`，共享同一份文档和版本。`--cwd` 只改变工作目录。需要隔离缓存时，必须为三个进程设置相同的绝对路径 `APISKILL_CACHE_DIR`。开发本仓库时也可以使用：
 
 ```bash
 npm install

package/mcp-config.example.json

@@ -3,11 +3,7 @@
     "apiskill": {
       "command": "node",
       "args": ["/Users/dobby/dev/apiskill/scripts/mcp-server.mjs"],
-      "cwd": "/Users/dobby/dev/apiskill",
-      "env": {
-        "APISKILL_ROOT": "/Users/dobby/dev/apiskill",
-        "APISKILL_CACHE_DIR": "/Users/dobby/dev/apiskill/cache"
-      }
+      "cwd": "/Users/dobby/dev/apiskill"
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apiskill",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "type": "module",
   "files": [
     "src",
@@ -22,6 +22,7 @@
     "dev": "vite --host 0.0.0.0 && node scripts/mcp-server.mjs",
     "build": "tsc -b && vite build",
     "test:cli-concurrency": "node scripts/test-cli-concurrency.mjs",
+    "test:shared-cache": "node scripts/test-shared-cache.mjs",
     "prepack": "npm run build",
     "preview": "vite preview --host 0.0.0.0",
     "mcp": "node scripts/mcp-server.mjs",

package/scripts/apiskill-cli.mjs

@@ -67,8 +67,7 @@ run
   .option('-p, --port <number>', 'Web server port', '8888')
   .option('--host <host>', 'Host to bind', '127.0.0.1')
   .option('--strict-port', 'Fail if the requested port is already in use')
-  .option('--cwd <dir>', 'Project directory. Uses <cwd>/cache unless --cache-dir is provided')
-  .option('--cache-dir <dir>', 'Cache directory. Defaults to ~/.apiskill/cache')
+  .option('--cwd <dir>', 'Project working directory. Does not change the shared cache directory')
   .action(async (options) => {
     await runWeb(options);
   });
@@ -297,11 +296,7 @@ function registerMockCommand(command) {
 
 async function runWeb(options) {
   const projectRoot = resolve(options.cwd || process.cwd());
-  const cacheDir = options.cacheDir
-    ? resolve(projectRoot, options.cacheDir)
-    : options.cwd
-      ? resolve(projectRoot, 'cache')
-      : getDefaultCacheDir();
+  const cacheDir = getDefaultCacheDir();
   const port = Number(options.port) || 8888;
   const host = options.host || '127.0.0.1';
 

package/scripts/lib/apiskill-core.mjs

@@ -13,6 +13,7 @@ import {
   saveManualOperation,
 } from './openapi-store.mjs';
 import { crawlOpenApi, importFromCurl, importFromLocalFile, importFromUrl } from './openapi-importer.mjs';
+import { getDefaultCacheDir } from './cache-paths.mjs';
 
 const MAX_DEPTH = 12;
 
@@ -37,6 +38,7 @@ export const importExamples = {
 };
 
 export async function checkCache() {
+  const cacheDir = getDefaultCacheDir();
   const versions = await listCachedVersions();
   try {
     const { document, meta } = await readCachedDocument();
@@ -46,6 +48,7 @@ export async function checkCache() {
       return {
         ok: false,
         message: 'No usable cached OpenAPI document found. The latest cache exists, but it has no paths.',
+        cacheDir,
         versionsCount: versions.length,
         latestVersion: metaSummary(meta),
         importExamples,
@@ -54,6 +57,7 @@ export async function checkCache() {
     return {
       ok: true,
       message: 'API Skill cache is ready.',
+      cacheDir,
       versionsCount: versions.length,
       latestVersion: {
         ...metaSummary(meta),
@@ -66,6 +70,7 @@ export async function checkCache() {
     return {
       ok: false,
       message: 'No usable cached OpenAPI document found. Import or crawl a document first.',
+      cacheDir,
       error: error instanceof Error ? error.message : 'Unknown cache read error',
       versionsCount: versions.length,
       latestVersion: versions.find((version) => version.latest) ?? versions[0],
@@ -76,6 +81,7 @@ export async function checkCache() {
 
 export function formatCheckText(result) {
   const lines = [];
+  if (result.cacheDir) lines.push(`Cache: ${result.cacheDir}`);
   if (result.ok) {
     lines.push('OK: API Skill cache is ready.');
     if (result.latestVersion?.versionId) lines.push(`Latest version: ${result.latestVersion.versionId}`);

package/scripts/lib/cache-paths.mjs

@@ -3,6 +3,5 @@ import { resolve } from 'node:path';
 
 export function getDefaultCacheDir(env = process.env) {
   if (env.APISKILL_CACHE_DIR) return resolve(env.APISKILL_CACHE_DIR);
-  if (env.APISKILL_ROOT) return resolve(env.APISKILL_ROOT, 'cache');
   return resolve(homedir(), '.apiskill', 'cache');
 }

package/scripts/test-shared-cache.mjs

@@ -0,0 +1,140 @@
+import assert from 'node:assert/strict';
+import { createServer } from 'node:net';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { homedir, tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawn } from 'node:child_process';
+import { getDefaultCacheDir } from './lib/cache-paths.mjs';
+
+const projectRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const cliPath = resolve(projectRoot, 'scripts/apiskill-cli.mjs');
+const cacheDir = await mkdtemp(join(tmpdir(), 'apiskill-shared-cache-'));
+const port = await findFreePort();
+let webProcess;
+
+try {
+  assert.equal(getDefaultCacheDir({ APISKILL_ROOT: '/tmp/another-project' }), resolve(homedir(), '.apiskill', 'cache'));
+
+  const created = JSON.parse(
+    await runCli(['document', 'create', '--title', 'Shared Cache Test', '--doc-version', '1.0.0', '--json']),
+  );
+  const versionId = created.meta.versionId;
+  await runCli([
+    'api',
+    'create',
+    '--version',
+    versionId,
+    '--config',
+    JSON.stringify({
+      api: {
+        method: 'get',
+        path: '/api/v1/from-cli',
+        summary: 'Created from CLI',
+        responses: [{ status: '200', description: 'Success' }],
+      },
+    }),
+    '--json',
+  ]);
+
+  webProcess = spawn(
+    process.execPath,
+    [cliPath, 'run', 'web', '--host', '127.0.0.1', '--port', String(port), '--strict-port', '--cwd', projectRoot],
+    {
+      cwd: projectRoot,
+      env: { ...process.env, APISKILL_CACHE_DIR: cacheDir },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    },
+  );
+  const webOutput = collectProcessOutput(webProcess);
+  await waitForWeb(port, webProcess, webOutput);
+
+  const webCacheResponse = await fetch(`http://127.0.0.1:${port}/api/openapi/cache`);
+  assert.equal(webCacheResponse.status, 200);
+  const webCache = await webCacheResponse.json();
+  assert.equal(webCache.meta.versionId, versionId);
+  assert.ok(webCache.document.paths['/api/v1/from-cli']?.get, 'Web did not read the API created by CLI');
+
+  const webWriteResponse = await fetch(`http://127.0.0.1:${port}/api/openapi/custom-operation`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({
+      versionId,
+      config: {
+        method: 'post',
+        path: '/api/v1/from-web',
+        summary: 'Created from Web',
+        responses: [{ status: '201', description: 'Created' }],
+      },
+    }),
+  });
+  assert.equal(webWriteResponse.status, 200, await webWriteResponse.text());
+
+  const cliRead = JSON.parse(await runCli(['api', 'query', 'POST', '/api/v1/from-web', '--version', versionId]));
+  assert.equal(cliRead.path, '/api/v1/from-web');
+  assert.equal(cliRead.method, 'post');
+
+  const check = JSON.parse(await runCli(['check', '--json']));
+  assert.equal(check.cacheDir, cacheDir);
+  console.log(`Shared cache test passed: CLI and Web both read and wrote ${cacheDir}.`);
+} finally {
+  if (webProcess && webProcess.exitCode === null) {
+    webProcess.kill('SIGTERM');
+    await new Promise((resolvePromise) => webProcess.once('close', resolvePromise));
+  }
+  await rm(cacheDir, { recursive: true, force: true });
+}
+
+function runCli(args) {
+  return new Promise((resolvePromise, rejectPromise) => {
+    const child = spawn(process.execPath, [cliPath, ...args], {
+      cwd: projectRoot,
+      env: { ...process.env, APISKILL_CACHE_DIR: cacheDir },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    const output = collectProcessOutput(child);
+    child.on('error', rejectPromise);
+    child.on('close', (code) => {
+      if (code === 0) resolvePromise(output.stdout);
+      else rejectPromise(new Error(`apiskill ${args.join(' ')} failed (${code}): ${output.stderr || output.stdout}`));
+    });
+  });
+}
+
+function collectProcessOutput(child) {
+  const output = { stdout: '', stderr: '' };
+  child.stdout.setEncoding('utf8');
+  child.stderr.setEncoding('utf8');
+  child.stdout.on('data', (chunk) => {
+    output.stdout += chunk;
+  });
+  child.stderr.on('data', (chunk) => {
+    output.stderr += chunk;
+  });
+  return output;
+}
+
+async function waitForWeb(webPort, child, output) {
+  const deadline = Date.now() + 15_000;
+  while (Date.now() < deadline) {
+    if (child.exitCode !== null) throw new Error(`Web process exited early (${child.exitCode}): ${output.stderr || output.stdout}`);
+    try {
+      const response = await fetch(`http://127.0.0.1:${webPort}/api/openapi/versions`);
+      if (response.ok) return;
+    } catch {}
+    await new Promise((resolvePromise) => setTimeout(resolvePromise, 100));
+  }
+  throw new Error(`Timed out waiting for Web: ${output.stderr || output.stdout}`);
+}
+
+function findFreePort() {
+  return new Promise((resolvePromise, rejectPromise) => {
+    const server = createServer();
+    server.once('error', rejectPromise);
+    server.listen(0, '127.0.0.1', () => {
+      const address = server.address();
+      const freePort = typeof address === 'object' && address ? address.port : 0;
+      server.close((error) => (error ? rejectPromise(error) : resolvePromise(freePort)));
+    });
+  });
+}