@shinaps/skills 0.11.0 → 0.12.1

package/.agents/plugins/marketplace.json

@@ -1,10 +1,12 @@
 {
   "name": "shinaps-skills-codex",
   "interface": { "displayName": "Shinaps AI for Codex" },
-  "plugins": [{
-    "name": "shinaps",
-    "source": { "source": "local", "path": "./plugins/shinaps-codex" },
-    "policy": { "installation": "AVAILABLE", "authentication": "ON_USE" },
-    "category": "Developer Tools"
-  }]
+  "plugins": [
+    {
+      "name": "shinaps",
+      "source": { "source": "local", "path": "./plugins/shinaps-codex" },
+      "policy": { "installation": "AVAILABLE", "authentication": "ON_USE" },
+      "category": "Developer Tools"
+    }
+  ]
 }

package/README.md

@@ -21,7 +21,7 @@ Shinaps AIの利用者向け開発ワークフロー。Claude CodeとCodexそれ
 | `extract-rules` | PRレビューからruleを抽出する |
 | `simplify` | 目的から見直して不要な構造や手順を削る |
 | `verify-ui` | 対象環境の実画面で見た目・操作を確かめる |
-| `commit` | 検証できる単位へ分けてコミットする。自律モードは明示依頼時のみ |
+| `commit` | 開始時に通常（推奨）・自律を確認し、検証できる単位へ分けてコミットする |
 | `create-pr` | リポジトリの規約に合わせてPRを作成する |
 | `release` | 公開条件を確定し、対象バージョンの利用可能性を確認する |
 
@@ -46,9 +46,12 @@ Node.js 22以上と、`plugin marketplace add` / `plugin add` に対応したCod
 npx @shinaps/skills@latest install codex
 npx @shinaps/skills@latest update codex
 npx @shinaps/skills@latest uninstall codex
+npx @shinaps/skills@latest recover codex
 ```
 
-ローカル開発では、このcheckoutから `node bin/skills.mjs install codex` のように同じ操作を実行できる。
+`recover codex`は、中断した更新の記録が残っている場合に復元だけを行う。記録が無ければ何もしない。
+
+ローカル開発では、このcheckoutから `node bin/skills.ts install codex` のように同じ操作を実行できる。Node.js 22.18以上なら型除去でTypeScriptをそのまま実行する (ビルド不要)。
 
 CLIはスキルをCodex pluginとして登録し、13個のカスタムエージェントを`${CODEX_HOME:-~/.codex}/agents/`へ配置する。新しいセッションで`shinaps:dev`、`shinaps:review`等が読み込まれる。エージェントのモデルと推論設定は親セッションから継承し、調査・レビュー担当は読み取り専用を既定にする。親セッションの実行時設定が優先される場合もあるため、権限の強制境界とは扱わない。
 
@@ -56,12 +59,41 @@ CLIはスキルをCodex pluginとして登録し、13個のカスタムエージ
 
 uninstallはこのCLIのplugin・marketplace・管理済みエージェントを取り除く。個人用スキルと、別途登録したMCP接続・認証情報は保持する。
 
+### 自動更新（Codex / macOS）
+
+```sh
+npx @shinaps/skills@latest auto-update enable codex
+npx @shinaps/skills@latest auto-update status codex
+npx @shinaps/skills@latest auto-update check codex
+npx @shinaps/skills@latest auto-update disable codex
+```
+
+初期状態は無効。導入済みの利用者が`enable`するとmacOSのユーザーLaunchAgentを登録し、ログイン中に1日1回（12:00）確認する。スリープ中に12:00を過ぎた場合は起床時に1回だけ実行する。電源が切れていた回は実行しない。確認のたびにnpmから`latest`のパッケージを取得して実行し、導入版より新しい安定版の場合だけ更新する。古い版への自動ダウングレードはしない。更新内容は新しいCodexセッションから反映される。
+
+`enable`は通常のログインシェルから実行する。CodexやClaude Codeのセッション内からは実行しない。登録時のPATH、npmの場所、`CODEX_HOME`が記録され、以後の確認でもそのまま使われる。ツールの場所を変えた場合は再度`enable`する。npmの設定は`~/.npmrc`のものが使われる。
+
+登録直後に次の手順で動作を確認できる。`kickstart`はすぐに戻るので、npmの取得が終わるまで待ってから残りを実行する。
+
+```sh
+launchctl kickstart -k gui/$(id -u)/io.shinaps.skills.update
+launchctl print gui/$(id -u)/io.shinaps.skills.update | grep 'last exit code'
+npx @shinaps/skills@latest auto-update status codex
+```
+
+更新前に新版を準備し、旧スキル・エージェント・管理情報を退避する。更新中のエラー時は旧内容とCodexのプラグイン登録を復元する。強制終了などで復元できなかった場合は、次の更新確認時または`recover codex`の実行時に、`~/.local/share/shinaps-ai/skills/transaction/`に残った記録から復元する。復元にも失敗した場合は同じ場所にバックアップを保持して停止するので、エラーの原因を直してから`recover codex`を実行する。導入後のユーザー編集や同時更新は上書きせず停止する。
+
+`status`は設定と最終確認結果を表示する。失敗の詳細は`~/.local/share/shinaps-ai/skills/auto-update-error.log`、通常ログは同じ場所の`auto-update.log`に記録する。npmがパッケージを取得できなかった場合は最終確認結果は更新されず、エラーログだけに記録される。通知ポップアップは出さない。`disable`は予定実行を停止し、導入したスキルは保持する。`uninstall codex`は予定実行も停止する。
+
+macOS以外では予定実行の登録に対応していないため手動更新を使う。
+
+Claude Codeは標準のmarketplace自動更新機能を使う。`/plugin` のMarketplacesから対象marketplaceのauto-updateを有効にする。GitHubから自動取得するにはリモートmarketplaceを登録する必要があり、ローカルcheckout登録ではソースのgit pullまで自動実行しない。
+
 ## 開発と配布
 
-- Claude版: `plugins/shinaps/`、marketplaceは`.claude-plugin/marketplace.json`
+- Claude版: `plugins/shinaps-claude/`、marketplaceは`.claude-plugin/marketplace.json`
 - Codex版: `plugins/shinaps-codex/`、marketplaceは`.agents/plugins/marketplace.json`
-- Codexカスタムエージェント: `codex/agents/`
-- 配布CLI: `bin/skills.mjs` / `lib/install.mjs`
+- Codexカスタムエージェント: `plugins/shinaps-codex/agents/`
+- 配布CLI: ソースは `bin/skills.ts` と `lib/*.ts`。`npm run build` (`tsc`) で `dist/` にJSを出力し、npmにはそれを配布する。Node.jsは`node_modules`配下の`.ts`に型除去を適用しないため、ソースのままは配布できない。checkoutでは型除去で直接実行するので、`enum`など型除去で消せない構文は使わない (`tsconfig.json` の `erasableSyntaxOnly`)
 
 品質基準とプロジェクト設定の方針は揃えつつ、クライアント固有の実行手順・エージェント形式は別々に管理する。Claude向けのエージェント呼び出しをCodexに読み替えさせる方式は使わない。スキルを追加・変更した場合は両版への適用可否を判断する。
 
@@ -73,6 +105,20 @@ npm pack --dry-run
 
 公開前にはnpmスコープ`@shinaps`の利用権限とtarball内容を確認する。CLIのバージョンと両pluginのバージョンを揃える。開発中の同一バージョンも`update codex`で再配置できる。
 
+### CIとnpm自動公開
+
+`.github/workflows/publish.yml` はmainへのpush・PR・手動実行でテストと配布内容を検証する。通常のGitHub Releaseを公開すると、検証成功後に同じtagのパッケージをnpmへpublic公開する。prereleaseは公開しない。手動実行は検証専用で、npmへの公開は行わない。
+
+リリース時は`package.json`と両plugin manifestのバージョンを揃えてコミットし、`v<version>` tagを対象にGitHub Releaseを公開する。tagとバージョンが不一致なら停止する。既存のnpmバージョンは再公開できないため、次の変更には新しいバージョンを使う。
+
+npmの`@shinaps/skills`にGitHub ActionsのTrusted Publisherを登録する。GitHub ownerは`sh1n4ps`、repositoryは`shinaps-skills`、workflow filenameは`publish.yml`、direct publishを許可する。CIはGitHub-hosted Ubuntu・Node.js 24を使い、publish jobだけに`id-token: write`を付与する。`NPM_TOKEN` secretは不要。初回の信頼設定には本人認証が必要だが、その後のCI公開に毎回のセキュリティキー操作は不要。
+
+ローカルで同じ配布検証を行うには`npm run verify:package`を使う。`RELEASE_TAG=v<version>`を付ければtag整合性も確認できる。npmのprovenanceは公開リポジトリからのTrusted Publishingが対象で、privateリポジトリでは生成されない。
+
+### コード整形
+
+`npm ci` で開発依存を導入し、`npm run format` でBiomeによる整形を行う。`npm run check` は整形と型 (`tsc --noEmit`) を検証する。`npm pack` と `npm publish` は `prepack` で自動的に `npm run build` を実行する。`npm run verify:package` は配布物の一覧を比較したうえで、tarballを一時ディレクトリにinstallして起動できることを確認する。Biomeは整形用途で使用し、lintとimportの自動整理は無効。Markdown・TOMLのエージェント定義は整形対象外。
+
 ## Shinaps AIとの接続
 
 rule照合・抽出が必要な工程には `shinaps-ai` MCPを登録する。サービスURLは `https://app.shinaps.ai/mcp`。ClaudeとCodexそれぞれのMCP設定形式・ログイン手順に従う。開発用localhostはローカルサーバーを利用する場合だけ追加する。
@@ -114,7 +160,7 @@ codex mcp login shinaps-ai
 | `shinaps-debug-validator` | 仮説の実コード検証 (root-cause / contributing-factor / red-herring / needs-reproduction 分類) |
 | `shinaps-split-reviewer` | `shinaps:commit` の分割案を「単位の diff だけで妥当性を判断できるか」で批判 + 修正版最終分割計画 (worktree は read-only) |
 
-Claude版はMarkdown、Codex版はTOMLで役割を定義する。**subagent 内では shinaps MCP を直接叩かず、rule 全文は Skill 側から prompt 経由で渡す** 原則を全 system prompt に明記 (credit 最適化)。
+Claude版はMarkdown、Codex版はTOMLで役割を定義する。**subagent 内では shinaps MCP を直接呼び出さず、rule 全文は Skill 側から prompt 経由で渡す** 原則を全 system prompt に明記する。MCP呼び出しの利用量が重複しないようにするため。
 
 
 ## 作業成果物

package/dist/bin/skills.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { run } from '../lib/install.js';
+import { autoUpdate } from '../lib/auto-update.js';
+import { errorMessage } from '../lib/fs.js';
+const [command, ...rest] = process.argv.slice(2);
+try {
+    if (command === 'auto-update')
+        await autoUpdate(rest);
+    else
+        await run(process.argv.slice(2));
+}
+catch (error) {
+    console.error(`Shinaps: ${errorMessage(error)}`);
+    process.exitCode = 1;
+}

package/dist/lib/auto-update.js

@@ -0,0 +1,245 @@
+import { mkdir, writeFile, rm } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { execFileSync, spawnSync } from 'node:child_process';
+import { withLock } from './lock.js';
+import { install, openInstallation, recover } from './install.js';
+import { errorMessage, readJson, readJsonIfExists } from './fs.js';
+import { codexHomeMismatch, codexHomeOf, isRecordedCodexHome, managedRoot, manifestPath, payloadDir, statePath, } from './layout.js';
+const actions = ['enable', 'disable', 'status', 'check'];
+const isAction = (value) => actions.includes(value);
+const label = 'io.shinaps.skills.update';
+// StartInterval ではなく時刻指定にする。launchd はスリープ中に来た間隔の実行をスキップするが、時刻
+// 指定ならスリープ中に過ぎた回を起床時に 1 回実行する (man launchd.plist)。12:00 は Mac が起きていて
+// ログイン中である可能性が高い時刻として選んだ。
+const schedule = { hour: 12, minute: 0 };
+/**
+ * `shinaps-skills auto-update <enable|disable|status|check> codex`。
+ * @param args サブコマンドと対象。例: `['enable', 'codex']`。
+ * @param options 動作環境の指定。`auto-update check` とテストが使う。
+ */
+export async function autoUpdate(args, options = {}) {
+    const [action, target, ...extra] = args;
+    if (!isAction(action) || target !== 'codex' || extra.length) {
+        throw new Error(`Unknown command: auto-update ${args.join(' ')}. Usage: shinaps-skills auto-update <enable|disable|status|check> codex`);
+    }
+    const home = options.home ?? homedir();
+    const root = managedRoot(home);
+    const context = {
+        home,
+        root,
+        configPath: join(root, 'auto-update.json'),
+        resultPath: join(root, 'auto-update-result.json'),
+        log: options.log ?? console.log,
+        options,
+    };
+    // enable / disable / check は同じロックで直列にする。check の実行中に disable が走らないようにするため。
+    const schedulerDir = join(root, 'scheduler');
+    switch (action) {
+        case 'status':
+            return status(context);
+        case 'check':
+            return withLock(schedulerDir, () => check(context));
+        case 'disable':
+            return withLock(schedulerDir, () => disable(context));
+        case 'enable':
+            return withLock(schedulerDir, () => enable(context));
+    }
+}
+async function status(context) {
+    const config = await readJsonIfExists(context.configPath);
+    const lastCheck = await readJsonIfExists(context.resultPath);
+    context.log(JSON.stringify({ enabled: config !== null, config, lastCheck }, null, 2));
+}
+async function check(context) {
+    // 設定はロックを取ってから読む。取得前に読むと、その間に完了した disable を見逃し、無効にしたあとで
+    // 更新が実行されるため。
+    const config = await readJsonIfExists(context.configPath);
+    if (!config) {
+        throw new Error('Auto-update is not enabled. Run "shinaps-skills auto-update enable codex" first.');
+    }
+    const result = { checkedAt: new Date().toISOString() };
+    try {
+        await updateIfNewer(context, config, result);
+    }
+    catch (error) {
+        result.status = 'failed';
+        await recordResult(context.resultPath, result, error);
+        throw error;
+    }
+    await recordResult(context.resultPath, result);
+    context.log(JSON.stringify(result));
+}
+async function updateIfNewer(context, config, result) {
+    const installation = openInstallation({ ...context.options, codexHome: config.codexHome });
+    await recover(installation);
+    const state = await readJson(statePath(context.root));
+    if (!isRecordedCodexHome(state.codexHome, config.codexHome)) {
+        throw new Error(`Shinaps is installed in CODEX_HOME=${state.codexHome}, but auto-update is configured for ${config.codexHome}. Run "CODEX_HOME=${state.codexHome} shinaps-skills auto-update enable codex".`);
+    }
+    // 導入済みの版は配布物の manifest にある。state.json には記録していない。
+    result.installed = await packagedVersion(payloadDir(context.root));
+    // launchd ジョブは `npm exec @shinaps/skills@latest` でこのコマンドを起動するので、このプロセスの
+    // パッケージが最新版になる。導入済みより新しければ、このパッケージを配布元にして update する。
+    result.available = await packagedVersion(installation.source);
+    const updated = newer(result.available, result.installed);
+    if (updated) {
+        await install(installation, 'update');
+        result.installed = result.available;
+    }
+    result.status = updated ? 'updated' : 'up-to-date';
+}
+const packagedVersion = async (directory) => (await readJson(join(directory, manifestPath))).version;
+// 結果ファイルにはエラーメッセージを書かない。エラーは再 throw されて launchd のエラーログ
+// (auto-update-error.log) に出力されるので、詳細はそちらで確認する。結果ファイルには status と、読み
+// 取れた版だけを記録する。
+async function recordResult(path, result, failure) {
+    try {
+        await writeFile(path, JSON.stringify(result, null, 2) + '\n');
+    }
+    catch (writeError) {
+        if (failure === undefined)
+            throw writeError;
+        throw new AggregateError([failure, writeError], `${errorMessage(failure)}; result not recorded: ${errorMessage(writeError)}`, { cause: failure });
+    }
+}
+async function disable(context) {
+    const config = await readJsonIfExists(context.configPath);
+    // OS の確認より前に判定する。uninstall はどの OS でも disable を呼び、自動更新を有効にしたことのない
+    // 導入でもそこで失敗してはならない。
+    if (!config) {
+        context.log('Auto-update is already disabled.');
+        return;
+    }
+    const { service, plistPath, launchctl } = launchd(context);
+    await launchctl(['bootout', service]);
+    await rm(plistPath, { force: true });
+    await rm(context.configPath);
+    context.log('Daily auto-update disabled. Installed skills and agents were preserved.');
+}
+async function enable(context) {
+    const { home, root, configPath, options, log } = context;
+    const config = await readJsonIfExists(configPath);
+    const { uid, service, plistPath, launchctl } = launchd(context);
+    const state = await readJsonIfExists(statePath(root));
+    if (!state) {
+        throw new Error('Shinaps is not installed for Codex. Run "shinaps-skills install codex" first.');
+    }
+    const codexHome = codexHomeOf(options, home);
+    if (!isRecordedCodexHome(state.codexHome, codexHome)) {
+        throw new Error(`${codexHomeMismatch(state.codexHome, codexHome)} Run again with CODEX_HOME=${state.codexHome}.`);
+    }
+    const nextConfig = {
+        codexHome,
+        // `status` で表示する。同じパスが ProgramArguments の先頭にも入る。
+        npm: options.npm ?? execFileSync('/usr/bin/which', ['npm'], { encoding: 'utf8' }).trim(),
+    };
+    // ジョブは固定のコピーではなく、`npm exec @latest` で毎回最新版の CLI を取得して check を実行する
+    // (npm はタグを毎回オンラインで解決する)。そのため CLI 自体を更新する仕組みは持たない。代わりに、
+    // このコマンド行と各ファイルの形式は版をまたいで保つ (layout.ts の冒頭を参照)。
+    const plistText = renderPlist({
+        programArguments: [
+            nextConfig.npm,
+            'exec',
+            '--yes',
+            '--package',
+            '@shinaps/skills@latest',
+            '--',
+            'shinaps-skills',
+            'auto-update',
+            'check',
+            'codex',
+        ],
+        path: options.path ?? process.env.PATH ?? '',
+        root,
+    });
+    // 読み込み済みのラベルへの bootstrap は失敗するので、再 enable では先に今のジョブを外す。
+    if (config)
+        await launchctl(['bootout', service]);
+    await mkdir(dirname(plistPath), { recursive: true });
+    await writeFile(plistPath, plistText);
+    await writeFile(configPath, JSON.stringify(nextConfig, null, 2) + '\n');
+    try {
+        await launchctl(['bootstrap', `gui/${uid}`, plistPath]);
+    }
+    catch (error) {
+        try {
+            await rm(configPath, { force: true });
+            await rm(plistPath, { force: true });
+        }
+        catch (cleanup) {
+            throw new AggregateError([error, cleanup], `${errorMessage(error)}; cleanup failed: ${errorMessage(cleanup)}`, { cause: error });
+        }
+        throw error;
+    }
+    const time = `${schedule.hour}:${String(schedule.minute).padStart(2, '0')}`;
+    log(`Daily auto-update enabled: runs at ${time} while you are logged in (a run missed during sleep starts on wake).`);
+    log(`To test it now: launchctl kickstart -k ${service}`);
+    log(`Then check the result: shinaps-skills auto-update status codex (errors: ${join(root, 'auto-update-error.log')})`);
+}
+/** launchd の操作に必要な値。macOS 以外では throw する。 */
+function launchd(context) {
+    const { options, home } = context;
+    if ((options.platform ?? process.platform) !== 'darwin') {
+        throw new Error('Auto-update is available only on macOS. Run "shinaps-skills update codex" to update manually.');
+    }
+    // macOS であることを確認済みなので getuid は存在する。
+    const uid = options.uid ?? process.getuid();
+    return {
+        uid,
+        service: `gui/${uid}/${label}`,
+        plistPath: join(home, 'Library/LaunchAgents', `${label}.plist`),
+        launchctl: options.launch ?? launchctlCommand,
+    };
+}
+const launchctlCommand = (argv) => {
+    const result = spawnSync('/bin/launchctl', argv, { encoding: 'utf8' });
+    if (result.error)
+        throw result.error;
+    // 読み込まれていないラベルの bootout は終了コード 3 (ESRCH。`launchctl error 3` で意味を確認できる)
+    // で終わる。disable と再 enable はジョブが読み込まれていなくても続けるので、この場合だけ成功として
+    // 扱う。終了コードの意味は文書化されていないため、ほかの失敗は区別せずにエラーにする。
+    if (result.status !== 0 && !(argv[0] === 'bootout' && result.status === 3)) {
+        throw new Error(`launchctl ${argv[0]} failed: ${result.stderr.trim()}`);
+    }
+};
+function renderPlist(job) {
+    const entry = (argument) => `<string>${escapeXml(argument)}</string>`;
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+<key>Label</key><string>${label}</string>
+<key>ProgramArguments</key><array>${job.programArguments.map(entry).join('')}</array>
+<key>StartCalendarInterval</key><dict><key>Hour</key><integer>${schedule.hour}</integer><key>Minute</key><integer>${schedule.minute}</integer></dict>
+<key>EnvironmentVariables</key><dict><key>PATH</key><string>${escapeXml(job.path)}</string></dict>
+<key>WorkingDirectory</key><string>${escapeXml(job.root)}</string>
+<key>StandardOutPath</key><string>${escapeXml(join(job.root, 'auto-update.log'))}</string>
+<key>StandardErrorPath</key><string>${escapeXml(join(job.root, 'auto-update-error.log'))}</string>
+</dict></plist>
+`;
+}
+const xmlEntities = {
+    '<': '&lt;',
+    '>': '&gt;',
+    '&': '&amp;',
+    '"': '&quot;',
+    "'": '&apos;',
+};
+const escapeXml = (value) => value.replace(/[<>&"']/g, (character) => xmlEntities[character]);
+/** `candidate` が `installed` より新しい安定版か。安定版 (x.y.z) 以外は throw する。 */
+export function newer(candidate, installed) {
+    const parse = (value) => {
+        if (typeof value !== 'string' || !/^\d+\.\d+\.\d+$/.test(value)) {
+            throw new Error(`Expected a stable version, got ${value}`);
+        }
+        return value.split('.').map(Number);
+    };
+    const candidateParts = parse(candidate);
+    const installedParts = parse(installed);
+    for (let index = 0; index < 3; index++) {
+        if (candidateParts[index] !== installedParts[index]) {
+            return candidateParts[index] > installedParts[index];
+        }
+    }
+    return false;
+}

package/dist/lib/fs.js

@@ -0,0 +1,49 @@
+import { lstat, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { basename, dirname, join } from 'node:path';
+/** OS エラーの code (ENOENT など)。Error 以外や code を持たないエラーは undefined。 */
+export const errorCode = (error) => error instanceof Error ? error.code : undefined;
+export const errorMessage = (error) => error instanceof Error ? error.message : String(error);
+export const readJson = async (path) => JSON.parse(await readFile(path, 'utf8'));
+/** JSON ファイルを読む。無ければ null。 */
+export async function readJsonIfExists(path) {
+    try {
+        return await readJson(path);
+    }
+    catch (error) {
+        if (errorCode(error) === 'ENOENT')
+            return null;
+        throw error;
+    }
+}
+/**
+ * テキストファイルを読む。無ければ null。シンボリックリンクは辿らずに throw する。リンク先にある
+ * ユーザーのファイルを読み書きしないため。
+ */
+export async function readTextIfExists(path) {
+    try {
+        if ((await lstat(path)).isSymbolicLink()) {
+            throw new Error(`Symlink preserved: ${path}. Replace it with a regular file or remove it, then retry.`);
+        }
+        return await readFile(path, 'utf8');
+    }
+    catch (error) {
+        if (errorCode(error) === 'ENOENT')
+            return null;
+        throw error;
+    }
+}
+/**
+ * 同じディレクトリの一時ファイルに書いてから rename する。読む側が書きかけの内容を見ることはなく、
+ * 既存のシンボリックリンクも辿らずに置き換える。
+ */
+export async function writeFileAtomic(path, content) {
+    const temporary = join(dirname(path), `.${basename(path)}.${randomUUID()}.tmp`);
+    try {
+        await writeFile(temporary, content, { flag: 'wx' });
+        await rename(temporary, path);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}

package/dist/lib/install.js

@@ -0,0 +1,204 @@
+import { readFile, readdir, cp, rm, mkdir } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { digest, registerPlugin, replaceInstallation, restore, } from './transaction.js';
+import { withLock } from './lock.js';
+import { readTextIfExists, writeFileAtomic } from './fs.js';
+import { codexHomeMismatch, codexHomeOf, isRecordedCodexHome, managedAgent, managedRoot, marketplaceName, packageRoot, payloadDir, payloadPaths, pluginDir, pluginId, statePath, } from './layout.js';
+const actions = ['install', 'update', 'uninstall', 'recover'];
+const isAction = (value) => actions.includes(value);
+const usage = [
+    'Usage: shinaps-skills <install|update|uninstall|recover> codex',
+    '       shinaps-skills auto-update <enable|disable|status|check> codex',
+    'Claude Code: /plugin marketplace add sh1n4ps/shinaps-skills',
+    '             /plugin install shinaps@shinaps-skills',
+].join('\n');
+const installGuidance = [
+    'No Shinaps AI account is required to install. For MCP features, create an account at https://app.shinaps.ai and use your client’s authentication flow.',
+    'MCP setup (only if not already configured): codex mcp add shinaps-ai --url https://app.shinaps.ai/mcp',
+    'Then: codex mcp login shinaps-ai',
+];
+/**
+ * `shinaps-skills <install|update|uninstall|recover> codex` を実行する。どの操作も、開始時に中断した
+ * 更新があれば restore で元に戻す。
+ * @param args コマンドライン引数 (node とスクリプトのパスを除いたもの)。例: `['install', 'codex']`。
+ * @param options 動作環境の指定。`auto-update check` とテストが使う。
+ */
+export async function run(args, options = {}) {
+    const log = options.log ?? console.log;
+    const [action, target, ...extra] = args;
+    if (!action || action === '--help' || action === 'help') {
+        log(usage);
+        return;
+    }
+    if (!isAction(action) || target !== 'codex' || extra.length) {
+        throw new Error(`Unknown command: ${args.join(' ')}. ${usage.split('\n')[0]} (see --help).`);
+    }
+    const installation = openInstallation(options);
+    switch (action) {
+        case 'recover':
+            return recover(installation);
+        case 'uninstall':
+            return uninstall(installation, options);
+        case 'install':
+        case 'update':
+            return install(installation, action);
+    }
+}
+export function openInstallation(options) {
+    const home = options.home ?? homedir();
+    const codexHome = codexHomeOf(options, home);
+    return {
+        root: managedRoot(home),
+        codexHome,
+        agentsDir: join(codexHome, 'agents'),
+        command: options.command ?? codexCommand(codexHome),
+        source: options.source ?? packageRoot,
+        log: options.log ?? console.log,
+    };
+}
+/** 中断した更新があれば元に戻す。無ければ何もしない。 */
+export function recover(installation) {
+    return withLock(installation.root, () => restore(installation));
+}
+/**
+ * 配布物とエージェントを `installation.source` の内容に置き換える。state.json の記録と違うエージェントが
+ * あれば何も変更せずに止める。
+ * @param action install と update の違いは完了メッセージだけ。
+ */
+export async function install(installation, action) {
+    const { root, codexHome, agentsDir, command, log } = installation;
+    await withLock(root, async () => {
+        await restore(installation);
+        const recorded = await readVerifiedState(installation);
+        const state = recorded?.state ?? { agents: {}, codexHome };
+        const nextAgents = await readPackagedAgents(installation, state);
+        const preparedDir = await preparePayload(installation);
+        const journal = {
+            state: recorded?.text ?? null,
+            agents: {},
+            codexHome,
+            nextHashes: {},
+        };
+        for (const name of new Set([...Object.keys(state.agents), ...Object.keys(nextAgents)])) {
+            journal.agents[name] = await readTextIfExists(join(agentsDir, name));
+            journal.nextHashes[name] = nextAgents[name]?.hash ?? null;
+        }
+        const nextState = {
+            agents: Object.fromEntries(Object.entries(nextAgents).map(([name, { hash }]) => [name, hash])),
+            codexHome,
+        };
+        const removed = Object.keys(state.agents).filter((name) => !(name in nextAgents));
+        await replaceInstallation(installation, journal, preparedDir, async () => {
+            // codex コマンドより前に作る。codex は既定のディレクトリだけを自分で作り、指定された
+            // CODEX_HOME が存在しないと失敗するため。
+            await mkdir(agentsDir, { recursive: true });
+            await registerPlugin(command, payloadDir(root));
+            for (const [name, { content }] of Object.entries(nextAgents)) {
+                await writeFileAtomic(join(agentsDir, name), content);
+            }
+            for (const name of removed)
+                await rm(join(agentsDir, name), { force: true });
+            await writeFileAtomic(statePath(root), JSON.stringify(nextState, null, 2) + '\n');
+        });
+    });
+    if (action === 'update') {
+        log('Shinaps updated. Start a new Codex session to load the new skills and agents.');
+        return;
+    }
+    log('Shinaps installed. Start a new Codex session to load skills and agents.');
+    for (const line of installGuidance)
+        log(line);
+}
+async function uninstall(installation, options) {
+    const { root, agentsDir, command, log } = installation;
+    await withLock(root, async () => {
+        await restore(installation);
+        const recorded = await readVerifiedState(installation);
+        if (!recorded) {
+            log('No managed Shinaps installation found.');
+            return;
+        }
+        // auto-update.ts は check でこのモジュールを使う。相互 import を避けるため実行時に読み込む。
+        const { autoUpdate } = await import('./auto-update.js');
+        await autoUpdate(['disable', 'codex'], options);
+        await command(['plugin', 'remove', pluginId]);
+        await command(['plugin', 'marketplace', 'remove', marketplaceName]);
+        for (const name of Object.keys(recorded.state.agents)) {
+            await rm(join(agentsDir, name), { force: true });
+        }
+        await rm(payloadDir(root), { recursive: true, force: true });
+        await rm(statePath(root));
+        log('Removed managed Codex plugin and agents. Other skills and MCP credentials were preserved.');
+    });
+}
+// codex にはファイル操作と同じ CODEX_HOME を見せる。options.codexHome (`auto-update check` が渡す)
+// はシェルの環境変数と違い得るので、解決済みの値を明示的に渡す。
+const codexCommand = (codexHome) => (argv) => {
+    const result = spawnSync('codex', argv, {
+        stdio: 'inherit',
+        env: { ...process.env, CODEX_HOME: codexHome },
+    });
+    if (result.error)
+        throw result.error;
+    if (result.status !== 0) {
+        throw new Error(`codex ${argv.join(' ')} exited with ${result.status ?? result.signal}. Fix the error codex reported above, then retry.`);
+    }
+};
+/**
+ * state.json を読み、記録された導入先とエージェントを今回の実行で扱えることを確かめる。無ければ null。
+ * 名前の接頭辞は所有の証明にならないので、記録した内容と一致するファイルだけを置き換え・削除する。
+ * ユーザーが編集したファイルがあれば、何も変更しないうちに止めて、移動か復元を求める。
+ */
+async function readVerifiedState(installation) {
+    const { root, codexHome, agentsDir } = installation;
+    const path = statePath(root);
+    const text = await readTextIfExists(path);
+    if (text === null)
+        return null;
+    const state = JSON.parse(text);
+    // state.json は記録した CODEX_HOME のエージェントだけを管理する。別の CODEX_HOME で実行した
+    // uninstall が、そちらにある同名のファイルを削除しないように、一致しなければ止める。
+    if (!isRecordedCodexHome(state.codexHome, codexHome)) {
+        throw new Error(`${codexHomeMismatch(state.codexHome, codexHome)} Run again with CODEX_HOME=${state.codexHome}, or run "CODEX_HOME=${state.codexHome} shinaps-skills uninstall codex" first.`);
+    }
+    for (const [name, hash] of Object.entries(state.agents)) {
+        if (!managedAgent.test(name))
+            throw new Error(`Invalid agent filename "${name}" in ${path}.`);
+        const current = await readTextIfExists(join(agentsDir, name));
+        if (current === null)
+            continue;
+        const currentHash = digest(current);
+        if (currentHash !== hash && currentHash !== state.pending?.[name]) {
+            throw new Error(`Modified agent preserved: ${join(agentsDir, name)}. Move the edited file elsewhere or restore its content, then retry.`);
+        }
+    }
+    return { text, state };
+}
+/** パッケージに入っているエージェント。導入先に Shinaps が置いていない同名ファイルがあれば止める。 */
+async function readPackagedAgents(installation, state) {
+    const { source, agentsDir } = installation;
+    const directory = join(source, pluginDir, 'agents');
+    const agents = {};
+    for (const name of await readdir(directory)) {
+        if (!managedAgent.test(name))
+            continue;
+        const content = await readFile(join(directory, name), 'utf8');
+        if (!(name in state.agents) && (await readTextIfExists(join(agentsDir, name))) !== null) {
+            throw new Error(`Unmanaged agent preserved: ${join(agentsDir, name)}. Shinaps did not install this file. Move or rename it, then retry.`);
+        }
+        agents[name] = { content, hash: digest(content) };
+    }
+    return agents;
+}
+// npx のダウンロードキャッシュは一時的。配布物は管理ディレクトリにコピーし、後続の Codex セッションと
+// 更新がキャッシュに依存しないようにする。
+async function preparePayload(installation) {
+    const prepared = join(installation.root, 'prepared');
+    await rm(prepared, { recursive: true, force: true });
+    for (const path of payloadPaths) {
+        await cp(join(installation.source, path), join(prepared, path), { recursive: true });
+    }
+    return prepared;
+}