Bm Code Management

BaseMachina コード管理 skill

コマンド・フラグ・型・ビュー連携の詳細は記憶で書かず、公式ドキュメント（）と SDK / runtime の型定義（node_modules/@basemachina/sdk / @basemachina/action）を都度確認する。

いつ使うか

• defineAction / defineConfig を新規作成・編集する
• JavaScript アクションのコード本体を新規作成・編集する
• コードエディターのビューコードを同じ repo に置き、コード取得設定と組み合わせる
• Web UI で作成した未取り込みアクションを bm pull でコード管理へ取り込む相談を受ける
• bm sync --dry で差分をプレビューしてユーザーに示す
• 認証切れや TypeScript 型エラーから復旧する

いつ使わないか

• アクションの実行（テスト含む）
• ビュー設定そのもののコード管理。公式 docs 上、ビューの設定はコード管理対象外で、ビュー内コードのみコード取得設定と組み合わせて同居できる
• 本番への実反映（bm sync を --dry 抜きで叩く操作）。実反映は CI 経由、または明示的なユーザー操作に委ねる

領域選択（navigation）

ユーザーの作業内容に応じて、以下の reference を必要なものだけ読み込む。

| 作業 | 読むべき reference | | --- | --- | | basemachina.config.ts / defineAction / defineConfig を編集 | [references/ts-config.md](references/ts-config.md) | | JavaScript アクションのコード本体を書く・直す（executeAction / createActionJob / wait / ResultError など） | [references/js-action.md](references/js-action.md) | | views/**/*.tsx / @basemachina/view / コード取得設定 / ビューコードの build・配置 | [references/view-code.md](references/view-code.md) |

複数領域に跨る場合（例: TS 設定で JS アクションを宣言し、コード本体も書く）は、該当する reference を順次 Read する。

共通: Pre-flight

1. basemachina.config.ts がカレントディレクトリのルートに存在することを確認する。無ければ --config 指定またはプロジェクトルートへの移動を依頼する
2. 下記「パッケージマネージャー」の手順で PM を 1 つに確定する。以降の install / outdated / 最新化 / TypeScript チェックはすべて確定した PM のものを使う
3. @basemachina/sdk / @basemachina/cli のインストール状態を確認する（CLI は bm --version の成功、SDK は package.json の dependencies / devDependencies への記載で判定）。未インストールがあればユーザーに「インストールしますか？」と確認し、yes の場合に限り PM ごとの dev 依存追加 コマンドを実行する
4. PM ごとの outdated コマンドで @basemachina/sdk / @basemachina/cli の新バージョンの有無を確認する。新バージョンがあればユーザーに「更新しますか？」と確認し、yes の場合に限り PM ごとの 最新化 コマンドを実行する。package.json を Read して devDependency に入っているパッケージには dev フラグを付ける。yarn berry など outdated 相当が無い PM では確認をスキップしてユーザーに任意ツールでの確認を促す
5. JS アクションを扱う場合は @basemachina/action（runtime 型定義）のインストールも併せて確認する
6. ビューコードを扱う場合は @basemachina/view の docs、tsconfig.json の JSX 設定、react / @types/react のインストール状態を確認する

共通: パッケージマネージャー

検出（優先度順）

1. package.json の packageManager フィールドを最優先で使う。例: "packageManager": "pnpm@8.6.0" → pnpm。Corepack 対応プロジェクトの公式指定であり最も信頼できる
2. ロックファイルで判定する。pnpm-lock.yaml → pnpm / yarn.lock → yarn（ルートに .yarnrc.yml があれば berry、無ければ classic）/ bun.lockb または bun.lock → bun / package-lock.json → npm
3. どれも該当しないか複数ヒットした場合はユーザーに「どの PM を使いますか？」と確認する。複数のロックファイルが共存していたら「どれが正で、他は削除すべきか」も併せて確認する。packageManager フィールドとロックファイルが食い違う場合も同様に確認する

コマンド対応表

| 操作 | npm | yarn (classic) | yarn (berry) | pnpm | bun | | --- | --- | --- | --- | --- | --- | | dev 依存追加 | npm i -D | yarn add -D | yarn add -D | pnpm add -D | bun add -d | | 最新化（dep） | npm i @latest | yarn add @latest | yarn add @latest | pnpm add @latest | bun add @latest | | 最新化（devDep） | npm i -D @latest | yarn add -D @latest | yarn add -D @latest | pnpm add -D @latest | bun add -d @latest | | outdated 確認 | npm outdated | yarn outdated | （標準では無い。スキップ） | pnpm outdated | bun outdated | | ローカルバイナリ実行（tsc 等） | npx tsc | yarn tsc | yarn tsc | pnpm exec tsc | bunx tsc |

各 reference 内で tsc 等を指している箇所は、検出した PM の「ローカルバイナリ実行」コマンドに読み替える。

共通: bm sync の使い分け（ガードレール）

• エージェントから実行できるのは bm sync --dry のみ（allowed-tools で制限）
• 差分の意図が編集と一致するかを必ずユーザーに引き渡し、実反映は CI またはユーザー手動操作に委ねる
• JavaScript アクションの code 本文は dry-run 出力では省略されるため、本文差分の確認には git diff を使う
• フラグ詳細は bm sync --help または を参照する
• CI/CD の運用詳細は を参照する。PR では bm sync --dry、マージ後や環境デプロイでは CI が bm sync / bm sync を担う前提で説明する

共通: bm pull の扱い

• bm pull は、設定ファイルにまだ含まれていない Web UI 作成アクションを repo に取り込むためのコマンド
• 主な更新対象は src/actions/、src/bm-refs.ts、type.d.ts、設定ファイルへの import / actions 追記
• 既に設定ファイルに含まれているアクションの Web UI 変更は bm pull 対象外。Web UI 側の変更を取り込みたい場合は、設定ファイルを手動更新するか、設定を再ダウンロードして該当ファイルだけ差し替える
• bm pull は対話確認後にファイルを書き込むため、エージェントが実行する場合は事前にユーザーへ確認する
• 詳細は を参照する

共通: 認証

bm sync --dry がローカルで authentication required 等で失敗したら、ユーザーに bm login の実行を依頼する。bm login はブラウザを開く interactive フローで、エージェントから実行すると state トークンの受け渡しで破綻する。

参照先

• 公式ドキュメント（コード管理トップ）:
• 設定ファイル:
• bm pull CLI:
• bm sync CLI:
• CI/CD:
• JS アクション:
• ビューコードの Git 管理:
• コード取得設定との連携:
• SDK の型定義: node_modules/@basemachina/sdk/dist/oac/index.d.ts
• JS アクション runtime 型: node_modules/@basemachina/action/dist/*.d.ts
• CLI のフラグ一覧: bm sync --help

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: basemachina
• Source: basemachina/skills
• License: MIT
• Homepage: https://docs.basemachina.com/preview/code_management/

Install and usage instructions live in the source repository linked above.