@exabugs/dynamodb-client 1.19.0 → 1.21.0

package/dist/tools/dynamodb-system-change/releases.js

@@ -0,0 +1,108 @@
+/**
+ * terraform の plan / apply のログから、Lambda のコードのリリース（作成・置き換え・コードの更新）の成功・失敗を取り出す。
+ *
+ * asanowa（ADR 0044）・astro（ADR-0011）の `infra/scripts/parse-lambda-releases.py` を Node に移植したもの
+ * （両アプリの版は、ロジックが同一。違いは docstring だけ）。出力は Python 版と同じ（テストで固定）。
+ *
+ * 取り出す条件（Terraform 1.x と AWS プロバイダ 6.x の実際の出力で確認済み）:
+ * - 計画の `# <アドレス> will be created / must be replaced / will be replaced, as requested / will be updated in-place`
+ *   のうち、aws_lambda_function で、作成・置き換え、または更新で `source_code_hash` の差分があるもの（= コードが変わる）。
+ *   設定だけの更新（環境変数・同時実行数など）は、対象外
+ * - 成功: `<アドレス>: Modifications complete after … [id=<関数名>]`（更新）/ `Creation complete after … [id=<関数名>]`（作成）
+ * - 失敗: `Error: creating Lambda Function (<名前>)` / `Error: updating Lambda Function (<名前>) code` /
+ *   `Error: waiting for Lambda Function (<名前>) code update|create`（設定の更新の失敗は、対象外）
+ */
+/** 取り出す上限（Python 版の MAX_ITEMS） */
+export const EXTRACT_MAX_ITEMS = 50;
+/** 色コード（Python 版の ANSI） */
+export const ANSI_PATTERN = /\x1b\[[0-9;]*m/g;
+const ADDR = String.raw `\S*aws_lambda_function\.[A-Za-z0-9_]+(?:\[[^\]\n]*\])?`;
+// 見出しの言い方: will be created / will be updated in-place / must be replaced / will be replaced, as requested（-replace）/
+// is tainted, so must be replaced / will be destroyed
+const HEADER = new RegExp(String.raw `^\s*# (` +
+    ADDR +
+    String.raw `) (will be created|will be updated in-place|will be destroyed|` +
+    String.raw `(?:is tainted, so )?must be replaced|will be replaced, as requested)`);
+const ANY_HEADER = /^\s*# \S+ (?:will|must|is) /;
+const DONE = new RegExp('^(' + ADDR + String.raw `): (Modifications|Creation) complete after \S+ \[id=([^\]\s]+)\]`);
+const FAILED = [
+    [/Error: creating Lambda Function \(([^)\s]+)\)/, 'create'],
+    [/Error: updating Lambda Function \(([^)\s]+)\) code/, 'code'],
+    [/Error: waiting for Lambda Function \(([^)\s]+)\) code update/, 'code'],
+    [/Error: waiting for Lambda Function \(([^)\s]+)\) create/, 'create'],
+];
+/**
+ * Python の `str.splitlines()` と同じ区切りで行に分ける（\r\n、\n、\r、\v、\f、\x1c〜\x1e、\x85、U+2028、U+2029）。
+ * 末尾の区切りの後ろに空の行を作らない
+ */
+export function splitLines(text) {
+    const lines = text.split(/\r\n|[\n\r\v\f\x1c\x1d\x1e\x85\u2028\u2029]/);
+    if (lines.length > 0 && lines[lines.length - 1] === '')
+        lines.pop();
+    return lines;
+}
+/** 色コードを除く */
+export function stripAnsi(text) {
+    return text.replace(ANSI_PATTERN, '');
+}
+/** 計画の見出しから「コードが変わる Lambda のアドレス → 変更の種類」を作る */
+function codeChangesOf(lines) {
+    const changes = new Map();
+    let i = 0;
+    while (i < lines.length) {
+        const m = HEADER.exec(lines[i]);
+        if (!m) {
+            i += 1;
+            continue;
+        }
+        const [, addr, action] = m;
+        let j = i + 1;
+        while (j < lines.length &&
+            !ANY_HEADER.test(lines[j]) &&
+            !lines[j].startsWith('Plan:') &&
+            !lines[j].startsWith('Do you want')) {
+            j += 1;
+        }
+        const block = lines.slice(i + 1, j);
+        if (action === 'will be created')
+            changes.set(addr, 'create');
+        else if (action.includes('replaced'))
+            changes.set(addr, 'replace');
+        else if (action === 'will be updated in-place' &&
+            block.some((l) => l.includes('source_code_hash'))) {
+            changes.set(addr, 'code');
+        }
+        i = j;
+    }
+    return changes;
+}
+/** ログから Lambda のリリースを取り出す（該当が無ければ空の配列。最大 EXTRACT_MAX_ITEMS 件） */
+export function extractLambdaReleases(text) {
+    const lines = splitLines(text).map(stripAnsi);
+    const codeChanges = codeChangesOf(lines);
+    const out = [];
+    const seen = new Set();
+    for (const raw of lines) {
+        const line = raw.replace(/^[│ ]+/, '').trimEnd();
+        const done = DONE.exec(line);
+        const change = done ? codeChanges.get(done[1]) : undefined;
+        if (done && change) {
+            const name = done[3];
+            if (!seen.has(name)) {
+                seen.add(name);
+                out.push({ target: name, result: 'succeeded', change });
+            }
+            continue;
+        }
+        for (const [rx, failedChange] of FAILED) {
+            const m = rx.exec(line);
+            if (m && !seen.has(m[1])) {
+                seen.add(m[1]);
+                out.push({ target: m[1], result: 'failed', change: failedChange });
+                break;
+            }
+        }
+    }
+    return out.slice(0, EXTRACT_MAX_ITEMS);
+}
+//# sourceMappingURL=releases.js.map

package/dist/tools/dynamodb-system-change/releases.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"releases.js","sourceRoot":"","sources":["../../../src/tools/dynamodb-system-change/releases.ts"],"names":[],"mappings":"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"}

package/dist/tools/dynamodb-system-change/run.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=run.d.ts.map

package/dist/tools/dynamodb-system-change/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../../src/tools/dynamodb-system-change/run.ts"],"names":[],"mappings":""}

package/dist/tools/dynamodb-system-change/run.js

@@ -0,0 +1,6 @@
+import { main } from './cli.js';
+process.exitCode = main(process.argv.slice(2), {
+    out: (s) => process.stdout.write(s),
+    err: (s) => process.stderr.write(s),
+});
+//# sourceMappingURL=run.js.map

package/dist/tools/dynamodb-system-change/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../../../src/tools/dynamodb-system-change/run.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AAEhC,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE;IAC7C,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IACnC,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;CACpC,CAAC,CAAC"}

package/dist/tools/dynamodb-system-change/send.d.ts

@@ -0,0 +1,43 @@
+/** 外部コマンドの実行（テストで差し替える） */
+export type RunCommand = (command: string, args: string[], options?: {
+    cwd?: string;
+}) => {
+    status: number | null;
+    stdout: Buffer;
+    stderr: Buffer;
+    error?: Error;
+};
+export declare const runCommand: RunCommand;
+/** 記録 Lambda に送る本文（記録 Lambda の入力。キーの順は現行と同じ） */
+export interface SystemChangePayload {
+    kind: string;
+    result: 'started' | 'succeeded' | 'failed';
+    target: string;
+    commit: string;
+    actor: string;
+    details: Record<string, unknown>;
+    changeId?: string;
+}
+/**
+ * Python の `json.dumps(x, ensure_ascii=False)` と同じ文字列（区切りは `, ` と `: `）。
+ * 送る内容（--payload）と、RECORD_DRY_RUN の表示を、現行と一字一句同じにするため
+ */
+export declare function pythonJsonDumps(value: unknown): string;
+/**
+ * コミット（`git rev-parse --short HEAD`。取れなければ unknown）。dirtyPaths に未コミットの変更があれば `-dirty`
+ * （`git diff-index --quiet HEAD -- <paths>` が 0 以外。git が無い・失敗も -dirty。現行と同じ）
+ */
+export declare function commitOf(repo: string | undefined, dirtyPaths: string[], run?: RunCommand): string;
+/** 実行者（`$(whoami)@$(hostname -s)`） */
+export declare function actorOf(): string;
+export interface SendOptions {
+    functionName: string;
+    region: string;
+    dryRun: boolean;
+    /** 警告の出力先（標準エラー。バイト列も受ける） */
+    warn: (message: string | Buffer) => void;
+    run?: RunCommand;
+}
+/** 記録 Lambda を呼ぶ。失敗は警告だけ（例外にしない）。記録 Lambda が無い環境は黙ってスキップ */
+export declare function sendSystemChange(payload: SystemChangePayload, options: SendOptions): void;
+//# sourceMappingURL=send.d.ts.map

package/dist/tools/dynamodb-system-change/send.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"send.d.ts","sourceRoot":"","sources":["../../../src/tools/dynamodb-system-change/send.ts"],"names":[],"mappings":"AAUA,2BAA2B;AAC3B,MAAM,MAAM,UAAU,GAAG,CACvB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,KACvB;IAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,KAAK,CAAA;CAAE,CAAC;AAE9E,eAAO,MAAM,UAAU,EAAE,UAQxB,CAAC;AAEF,gDAAgD;AAChD,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAC;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAOtD;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,EAAE,GAAG,aAAa,GAAG,MAAM,CAOjG;AAED,sCAAsC;AACtC,wBAAgB,OAAO,IAAI,MAAM,CAEhC;AAED,MAAM,WAAW,WAAW;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,6BAA6B;IAC7B,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,KAAK,IAAI,CAAC;IACzC,GAAG,CAAC,EAAE,UAAU,CAAC;CAClB;AAYD,4DAA4D;AAC5D,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,mBAAmB,EAAE,OAAO,EAAE,WAAW,GAAG,IAAI,CAsCzF"}

package/dist/tools/dynamodb-system-change/send.js

@@ -0,0 +1,97 @@
+/**
+ * 記録 Lambda（`<app>-<env>-system-change-recorder`）への送信（両アプリの terraform-wrapper.sh の record_change を
+ * 移植したもの）。
+ *
+ * 経路は現行のまま: AWS CLI の `aws lambda invoke`（認証は AWS CLI の認証情報。`AWS_PROFILE` などは環境変数で
+ * 引き継ぐ）。記録の失敗は、警告を出すだけで、例外にしない（apply・destroy を止めない）。
+ */
+import { spawnSync } from 'node:child_process';
+import { hostname, userInfo } from 'node:os';
+export const runCommand = (command, args, options) => {
+    const r = spawnSync(command, args, { cwd: options?.cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+    return {
+        status: r.status,
+        stdout: r.stdout ?? Buffer.alloc(0),
+        stderr: r.stderr ?? Buffer.alloc(0),
+        error: r.error,
+    };
+};
+/**
+ * Python の `json.dumps(x, ensure_ascii=False)` と同じ文字列（区切りは `, ` と `: `）。
+ * 送る内容（--payload）と、RECORD_DRY_RUN の表示を、現行と一字一句同じにするため
+ */
+export function pythonJsonDumps(value) {
+    if (Array.isArray(value))
+        return `[${value.map(pythonJsonDumps).join(', ')}]`;
+    if (value !== null && typeof value === 'object') {
+        const entries = Object.entries(value).filter(([, v]) => v !== undefined);
+        return `{${entries.map(([k, v]) => `${JSON.stringify(k)}: ${pythonJsonDumps(v)}`).join(', ')}}`;
+    }
+    return JSON.stringify(value);
+}
+/**
+ * コミット（`git rev-parse --short HEAD`。取れなければ unknown）。dirtyPaths に未コミットの変更があれば `-dirty`
+ * （`git diff-index --quiet HEAD -- <paths>` が 0 以外。git が無い・失敗も -dirty。現行と同じ）
+ */
+export function commitOf(repo, dirtyPaths, run = runCommand) {
+    const head = run('git', ['rev-parse', '--short', 'HEAD'], { cwd: repo });
+    let commit = head.status === 0 && !head.error ? head.stdout.toString('utf8').replace(/\n+$/, '') : 'unknown';
+    const diff = run('git', ['diff-index', '--quiet', 'HEAD', '--', ...dirtyPaths], { cwd: repo });
+    if (diff.status !== 0 || diff.error)
+        commit = `${commit}-dirty`;
+    return commit;
+}
+/** 実行者（`$(whoami)@$(hostname -s)`） */
+export function actorOf() {
+    return `${userInfo().username}@${hostname().split('.')[0]}`;
+}
+const PREFIX = '[change-record]';
+const NL = Buffer.from('\n');
+/** 末尾の改行（0x0a）を除く（bash の `$(...)` と同じ） */
+function trimTrailingNewlines(buf) {
+    let end = buf.length;
+    while (end > 0 && buf[end - 1] === 0x0a)
+        end -= 1;
+    return buf.subarray(0, end);
+}
+/** 記録 Lambda を呼ぶ。失敗は警告だけ（例外にしない）。記録 Lambda が無い環境は黙ってスキップ */
+export function sendSystemChange(payload, options) {
+    const body = pythonJsonDumps(payload);
+    if (options.dryRun) {
+        options.warn(`${PREFIX}[dry-run] ${options.functionName} <- ${body}\n`);
+        return;
+    }
+    const run = options.run ?? runCommand;
+    const r = run('aws', [
+        'lambda',
+        'invoke',
+        '--function-name',
+        options.functionName,
+        '--region',
+        options.region,
+        '--cli-binary-format',
+        'raw-in-base64-out',
+        '--cli-connect-timeout',
+        '5',
+        '--cli-read-timeout',
+        '30',
+        '--payload',
+        body,
+        '/dev/null',
+    ]);
+    // 現行は `out="$(… 2>&1)"`（標準出力と標準エラーをまとめ、末尾の改行を除く）
+    const errText = r.error ? Buffer.from(`${r.error.message}\n`) : Buffer.alloc(0);
+    const out = trimTrailingNewlines(Buffer.concat([r.stdout, r.stderr, errText]));
+    const text = out.toString('utf8');
+    if (r.status !== 0 || r.error) {
+        if (text.includes('ResourceNotFoundException'))
+            return; // 記録 Lambda が無い環境は、スキップ
+        // 現行は `$(echo "$out" | head -c 200)`（バイトで 200。末尾の改行は $(...) が除く）
+        const head = trimTrailingNewlines(Buffer.concat([out, NL]).subarray(0, 200));
+        options.warn(Buffer.concat([Buffer.from(`${PREFIX} 記録に失敗しました（処理は続行）: `), head, NL]));
+    }
+    else if (text.includes('"FunctionError"')) {
+        options.warn(`${PREFIX} 記録 Lambda がエラーを返しました（処理は続行）\n`);
+    }
+}
+//# sourceMappingURL=send.js.map

package/dist/tools/dynamodb-system-change/send.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"send.js","sourceRoot":"","sources":["../../../src/tools/dynamodb-system-change/send.ts"],"names":[],"mappings":"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"}

package/docs/DYNAMODB_ACCESS.md

@@ -138,7 +138,7 @@ ESLint は、エディタでも違反をその場で示す。CLI は ESLint の
 
 ## 許可リストの種別と約束
 
-- **恒久（permanent）**: 構造上必要な例外。このライブラリでは、Records の本体、Records が使う共有部品、別テーブル `notices`（`src/notify/store.ts`）。`notices` は例外ではなく原則の**対象外**（構造が違う別テーブルで、通知の重複抑制・流量制限の内部用。ビジネスのデータではない）。検査が IAM をテーブルごとに区別できないため permanent として載せる（ADR 0005）
+- **恒久（permanent）**: 構造上必要な例外。このライブラリでは、Records の本体、Records が使う共有部品、別テーブル `notices`（`src/notify/store.ts` と、通知 Lambda のロール `terraform/ops-notify` の `UpdateItem`）。`notices` は例外ではなく原則の**対象外**（構造が違う別テーブルで、通知の重複抑制・流量制限の内部用。ビジネスのデータではない）。検査が IAM をテーブルごとに区別できないため permanent として載せる（ADR 0005）
 - **負債（debt）**: 期限つき。消す作業が決まっている
 
 運用の約束:

package/docs/NOTIFY.md

@@ -1,6 +1,6 @@
 # 運用通知（`@exabugs/dynamodb-client/notify`）
 
-ログ（`warn` 以上）・CloudWatch アラーム・直接呼び出しを、管理者へ通知するための**部品**。配線（購読フィルタ・Lambda・Terraform・秘密の置き場）は、各アプリが行う。既存の挙動は変えない（サブパス `./notify` の追加のみ）。
+ログ（`warn` 以上）・CloudWatch アラーム・直接呼び出しを、管理者へ通知するための**部品**。配線のうち、Lambda のエントリと秘密の置き場は各アプリが行う。購読フィルタ・Lambda・テーブルの Terraform は `terraform/ops-notify`（1.21.0）。既存の挙動は変えない（サブパス `./notify` の追加のみ）。
 
 ```text
 ログ(購読フィルタ) ─┐
@@ -177,7 +177,7 @@ export const handler = createNotifyHandler({
 - 環境変数: 既存の `NOTICE_TABLE` / `RECORDS_IAM_URL` に加えて、`ADMIN_BASE_URL`（任意。無ければ URL を載せない）
 - IAM: 通知ストアへは `dynamodb:UpdateItem` だけ（既存の権限のまま。`GetItem` は要らない）。Records の IAM URL の呼び出し（`lambda:InvokeFunctionUrl`）は、管理者の一覧の取得で既に持っている
 - 同時実行数: 同じレコードへの同時の書き込みはシャドーを孤立させうるので、**記録を有効にするときだけ**、通知 Lambda の予約同時実行数を 1 にする（今の通知 Lambda は未設定。入れると、記録なしでも遅れ方が変わる）。直列化は努力目標で、強制はされない（打ち切った HTTP は止まらない・削除の定時処理と重なる・管理画面から書ける）。孤立したシャドーは `src/scripts/repair-shadows.ts` で修復できる
-- ライブラリは Terraform を提供しない（`alerts` の定時削除・同時実行数・環境変数は各アプリの infra で）
+- Terraform は `terraform/ops-notify`・`terraform/alerts-cleanup`（1.21.0。[README](../terraform/ops-notify/README.md)）。Lambda の成果物（エントリ）と、秘密の置き場は各アプリ
 
 ### 削除（定時 Lambda）
 

package/docs/SYSTEM_CHANGES.md

@@ -104,10 +104,77 @@ export const handler = createSystemChangeHandler({
 - 管理画面の一覧・詳細は `SystemChangesList` / `SystemChangesShow`（`@exabugs/dynamodb-client/integrations/react-admin`。1.19.0。[react-admin-integration.md](react-admin-integration.md#運用の画面alertssystemchanges)）
 - 投稿は notify の `postSlackText`（`createSlackChannel` と同じ送信。URL の接頭辞の確認、URL を出さないエラー）
 
+## 記録の CLI（`dynamodb-system-change`。1.20.0）
+
+terraform の apply・destroy の開始と終了を、記録 Lambda（`<app>-<env>-system-change-recorder`）に送る CLI（[ADR 0006](adr/0006-library-owns-table-operations.md) の段階 5 = (c)）。asanowa・astro の `terraform-wrapper.sh` の「記録に送る部分」（開始・終了の呼び出し、`details` の組み立て、`parse-lambda-releases.py`）を Node にした。**bash のラッパーは各アプリに残し**（state のバックエンド、plan の保存と確認、環境の検査はアプリごとに違う）、記録だけをこの CLI に委ねる。
+
+- 経路は従来のまま: AWS CLI の `aws lambda invoke`（`--cli-connect-timeout 5 --cli-read-timeout 30`。認証は AWS CLI の認証情報で、`AWS_PROFILE` などは環境変数で引き継ぐ）。送る本文は従来の Python の `json.dumps` と同じ文字列
+- **記録の失敗で apply を止めない**: `start` / `finish` は、記録の失敗・引数の誤りでも終了コード 0（警告は標準エラーに `[change-record] …`）。記録 Lambda が無い環境（`ResourceNotFoundException`）は黙ってスキップ。サブコマンドの誤りだけ 2
+- 受け渡し: `start` は変更 ID（ULID）を標準出力に 1 行で出す（記録の成否によらず。`SKIP_CHANGE_RECORD=1` では何も出さない）。ラッパーはシェルの変数に持ち、`finish --change-id` に渡す
+- 環境変数は従来と同じ: `RECORD_DRY_RUN=1`（呼ばずに、送る内容を表示）、`SKIP_CHANGE_RECORD=1`（記録しない）、`AWS_REGION`（無ければ `ap-northeast-1`）
+
+```text
+dynamodb-system-change start  --app <app> --env <env> --command <cmd> [共通]
+dynamodb-system-change finish --app <app> --env <env> --command <cmd> --exit-code <n> [--change-id <id>] [--log <file>] [共通]
+共通: [--repo <dir>] [--function <name>] [--target <target>] [--region <region>]
+      [--releases-max-items <n|none>] [--releases-max-bytes <n|none>] [--dirty-path <path>...]
+```
+
+| 引数                   | 内容                                                                                                                                       |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `--app` / `--env`      | `details.app` / `details.env`。既定の関数名 `<app>-<env>-system-change-recorder` と対象 `terraform:<app>` にも使う                         |
+| `--command`            | `details.command`（`apply` / `apply-auto` / `destroy` など）。`destroy` では Lambda のリリースを取り出さない                               |
+| `--exit-code`          | terraform の終了コード。0 は `succeeded`、それ以外は `failed` と `details.exit_code`                                                       |
+| `--log`                | plan / apply のログ。成功なら最後の完了の行から `add` / `change` / `destroy`、Lambda のリリースから `lambdaReleases`                       |
+| `--repo`               | git を実行するディレクトリ（既定: カレント）。`commit` は `git rev-parse --short HEAD`（取れなければ `unknown`）                           |
+| `--dirty-path`         | 未コミットの変更を調べる場所（`git diff-index --quiet HEAD -- <path>...`）。あれば `commit` に `-dirty`。最後に書く                        |
+| `--releases-max-items` | `lambdaReleases` の件数の上限（既定 `none`）                                                                                               |
+| `--releases-max-bytes` | `lambdaReleases` の JSON のバイト数の上限（既定 3000。details の上限 4096 に収める）。失敗を先に残し、省いた件数は `lambdaReleasesOmitted` |
+
+`actor` は `<ユーザー名>@<ホスト名の先頭>`（従来の `$(whoami)@$(hostname -s)`）。
+
+### ラッパーからの呼び方
+
+`set -euo pipefail` のラッパーでも止まらないよう、呼び出しには `|| true` を付ける（CLI が入っていない・node が無いときも apply を進める）。CLI が無いときは、記録が欠けたことに気づけるよう警告を出す。記録の部分は次のとおり（`$CHANGE_LOG` と `trap` の扱い、plan の確認はアプリのまま。`<…>` はアプリごとの値）:
+
+```bash
+SYSTEM_CHANGE="<node_modules の .bin>/dynamodb-system-change"   # npx は標準出力に余計な行を出しうるので使わない
+CHANGE_ARGS=(--app "<アプリ名>" --env "$ENV" --command "$COMMAND" [--repo "<git を実行する場所>"] --dirty-path <調べる場所>...)
+
+begin_change() {
+    [ -x "$SYSTEM_CHANGE" ] || echo "[change-record] CLI がありません（記録をスキップ）" >&2
+    CHANGE_ID="$("$SYSTEM_CHANGE" start "${CHANGE_ARGS[@]}" || true)"
+    CHANGE_OPEN=1
+}
+
+finish_change() {
+    local rc=$?
+    trap - EXIT
+    if [ "$CHANGE_OPEN" = "1" ]; then
+        CHANGE_OPEN=0
+        "$SYSTEM_CHANGE" finish "${CHANGE_ARGS[@]}" --change-id "$CHANGE_ID" --exit-code "$rc" --log "$CHANGE_LOG" || true
+    fi
+    rm -f "$CHANGE_LOG"
+    return "$rc"
+}
+```
+
+アプリごとの `CHANGE_ARGS`（従来の記録と同じ commit・details になる。`lambdaReleases` の上限は、両アプリとも既定の 3000 バイトを使う）:
+
+- **asanowa**: `--app "$APP" --env "$ENV" --command "$COMMAND" --dirty-path "$INFRA_ROOT" "$INFRA_ROOT/../functions" "$INFRA_ROOT/../packages"`（`--repo` は不要。ラッパーが `cd` した先で git を実行する）
+- **astro**: `--app "$PROJECT" --env "$ENV" --command "$COMMAND" --repo "$REPO_ROOT" --dirty-path infra apps functions packages`。上限は asanowa の既定（3000 バイト）に揃える（従来の「30 件まで」はやめる。件数の上限は付けない。64 文字の名前が並ぶと 30 件 → 約 27 件になり、超えた分は `lambdaReleasesOmitted` に残る）
+
+`--releases-max-items` / `--releases-max-bytes` は、既定と違う上限が要るときだけ使う。
+
+置き換えた後は、`record_change`・`new_change_id`・`finish_change` の Python と `parse-lambda-releases.py` を消せる。両アプリの `test-terraform-wrapper.sh` は、偽の `aws` を PATH に置く方式なので、そのまま使える（1.20.0 の開発時に、両アプリの検査がこの形のラッパーで全て通ることを確かめた）。
+
+部品（`@exabugs/dynamodb-client/system-changes/cli`）: `extractLambdaReleases(logText)`（`parse-lambda-releases.py` の移植。出力は同じ）、`buildFinishDetails` / `limitReleases` / `resourceCountsOf`、`main(argv, io, deps?)`。
+
 ## テスト
 
 - 単体: `src/system-changes/__tests__/`。ハンドラは、本物の `DynamoClient` に `fetch` だけを差し替えて固定する（`connect()` の呼び忘れを見逃さない）
 - 統合（DynamoDB Local。CI には入っていない）: `src/system-changes/__tests__/system-changes.integration.test.ts`（実行方法は PUBLISHING.md）
+- CLI: `__tests__/tools/dynamodb-system-change-*.test.ts`。Lambda のリリースの取り出しは、両アプリの本物のログ（`__tests__/tools/testdata/terraform-logs`。アカウント ID・URL・Cognito のユーザープール ID・ドメインは伏せた）で Python 版と同じ出力を固定する。送り方は偽の `aws` / `git`、止めないことは `set -euo pipefail` の bash のラッパーから CLI をプロセスとして呼んで確かめる
 
 ## アプリの移行（公開後の別作業）
 
@@ -116,4 +183,4 @@ ADR 0006 の段階 2 の手順: astro で先に置き換えて dev で確認し
 - Slack の文言は asanowa に揃えた。astro の「記録を省いた Lambda」は「ほかに記録しきれなかった Lambda」になる
 - Slack の送信は `postSlackText` を通る: webhook の URL が `https://hooks.slack.com/` で始まらないと送らない（`slack.urlPrefix`）。失敗の warn の理由は従来と同じ `HTTP 500` やエラー名（時間切れは `AbortError` ではなく `TimeoutError`）
 - asanowa の `changeId` の読み取りは `findOne`（404 を null にする）から `find({ id }, { sort: { id: 'asc' }, limit: 1 })`（Records の ID の経路。PK/SK の Query 1 回） に変わる。Records の ITEM_NOT_FOUND の warn が出なくなる
-- 記録 Lambda の Terraform（`source_file`）は、アプリのバンドルのまま（Terraform のモジュール化は段階 6）
+- 記録 Lambda の Terraform は `terraform/system-change-recorder`（1.21.0。段階 6。[README](../terraform/system-change-recorder/README.md)）。成果物はアプリのバンドルのまま（`source_file` で渡す）

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exabugs/dynamodb-client",
-  "version": "1.19.0",
+  "version": "1.21.0",
   "description": "DynamoDB Single-Table Client SDK with MongoDB-like API, Shadow Records, and Lambda implementation for serverless applications",
   "author": "exabugs",
   "license": "MIT",
@@ -8,7 +8,8 @@
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "bin": {
-    "dynamodb-access-check": "./bin/dynamodb-access-check.js"
+    "dynamodb-access-check": "./bin/dynamodb-access-check.js",
+    "dynamodb-system-change": "./bin/dynamodb-system-change.js"
   },
   "keywords": [
     "dynamodb",
@@ -129,6 +130,10 @@
     "./system-changes": {
       "import": "./dist/system-changes/index.js",
       "types": "./dist/system-changes/index.d.ts"
+    },
+    "./system-changes/cli": {
+      "import": "./dist/tools/dynamodb-system-change/index.js",
+      "types": "./dist/tools/dynamodb-system-change/index.d.ts"
     }
   },
   "peerDependencies": {

package/terraform/README.md

@@ -219,6 +219,15 @@ make logs-records ENV=dev
 aws logs tail /aws/lambda/my-project-dev-records --follow
 ```
 
+## 運用のモジュール（1.21.0）
+
+Records のクライアントとして動く運用の Lambda を、別のモジュールとして持つ（ADR 0006 の (b)）。Lambda の成果物（エントリ）はアプリが作り、`source_file` で渡す。
+
+- [ops-notify](ops-notify/README.md): 運用通知（ログ・アラーム・生存確認 → Slack とメール。alerts の記録）
+- [alerts-cleanup](alerts-cleanup/README.md): alerts の定時削除
+- [system-change-recorder](system-change-recorder/README.md): システム変更履歴の記録
+- [media](media/README.md): メディア（アップロード・処理・配信）
+
 ## 関連ドキュメント
 
 - [パッケージREADME](../README.md) - クライアントライブラリの使用方法

package/terraform/alerts-cleanup/README.md

@@ -0,0 +1,65 @@
+# alerts の定時削除 Lambda Terraformモジュール
+
+ADR 0006 の (b)（1.21.0）。asanowa・astro の `infra/modules/alerts-cleanup` を 1 つにしたもの。使い方の詳細は [docs/NOTIFY.md](../../docs/NOTIFY.md) の「削除（定時 Lambda）」。
+
+## 作るもの
+
+- Lambda `<project>-<env>-alerts-cleanup`（Node.js 22、arm64、120 秒、256 MB。構造化ログ JSON）と、そのロググループ・実行ロール
+- EventBridge の定時ルール（既定 毎日 03:00 JST）とターゲット（再試行 0）、呼び出しの許可
+- 権限: Records の IAM 版 URL の呼び出しだけ。DynamoDB には直接触れない
+- 環境変数: `PROJECT_NAME`（`createAlertsCleanupHandler` の `app` の既定）、`RECORDS_IAM_URL`
+
+## 前提
+
+- 参照は `node_modules` のパス（版は npm の版で固定される。git の `ref` ではない）。例: アプリの infra が `infra/` なら `source = "../node_modules/@exabugs/dynamodb-client/terraform/alerts-cleanup"`、`infra/apps/<app>/` なら `"../../../node_modules/..."`
+- **Lambda の成果物はアプリが作り、`source_file`（バンドル済みの 1 ファイル）と `handler` で渡す**。エントリはアプリの数行（`createAlertsCleanupHandler`。アプリ名や、権限チェック層を通すアプリの包み方を渡す）なので、ライブラリの dist は使わない
+- zip は `${path.root}/.terraform/archives/alerts-cleanup.zip` に作る（`path.module` を使わない。pnpm の版つきのパスが state に入ると、版を上げるたびに差分が出るため）
+- pnpm では、版を上げた後に `.terraform/modules` を消してから `terraform init` する（[../README.md](../README.md) の注意）
+- モジュール全体の `depends_on` は使わない（依存先に変更があると、中のデータソースが apply 時の読み取りになり、既存のリソースが作り直しになる）。依存は、出力の値（`log_group_name` など）で渡す
+
+## 使い方
+
+```hcl
+module "alerts_cleanup" {
+  source = "../node_modules/@exabugs/dynamodb-client/terraform/alerts-cleanup"
+
+  project_name             = var.project_name
+  environment              = var.environment
+  records_iam_function_url = module.records.iam_function_url
+  records_iam_alias_arn    = module.records.iam_alias_arn
+  log_retention_days       = var.log_retention_days
+
+  source_file = "${path.root}/../apps/server/dist/alerts-cleanup.cjs"
+  handler     = "alerts-cleanup.handler"
+}
+```
+
+## 変数
+
+| 変数                                                 | 既定                 | 説明                                                    |
+| ---------------------------------------------------- | -------------------- | ------------------------------------------------------- |
+| `project_name` / `environment`                       | 必須                 | 名前の接頭辞 `<project>-<env>`。環境変数 `PROJECT_NAME` |
+| `records_iam_function_url` / `records_iam_alias_arn` | 必須                 | Records の IAM 版 Function URL と、そのエイリアスの ARN |
+| `source_file` / `handler`                            | 必須                 | アプリのバンドル（1 ファイル）と、ハンドラ              |
+| `schedule_expression`                                | `cron(0 18 * * ? *)` | 実行間隔（毎日 03:00 JST）                              |
+| `log_retention_days`                                 | 7                    | ロググループの保持日数                                  |
+
+## 出力
+
+`function_name`、`function_arn`、`log_group_name`（ops-notify に購読させる）
+
+## アプリに残るもの
+
+- 上の module ブロック（`source`・`source_file`・`handler` と設定の値）
+- Lambda のエントリ（`createAlertsCleanupHandler` を呼ぶ数行）とバンドルの作成（esbuild など）
+- 秘密（webhook の URL など）の SSM パラメータの作成
+
+## アプリのモジュールからの移行（置き換えを起こさない）
+
+リソースのアドレス・名前は、asanowa / astro の旧モジュール（`infra/modules/alerts-cleanup`）と同じ。**module ブロックの名前（`module "alerts_cleanup"`）を変えずに `source` だけを差し替え**、`source_file`・`handler` を足す。アドレスが変わらないので `moved` は要らない（ラッパーのモジュールで包むと、アドレスが変わり `moved` が要る）。
+
+1. `terraform init`（モジュールの取り直し）→ `terraform plan`
+2. **0 to add / 0 to destroy、`must be replaced` が無い**ことを確かめる。出てよいのは in-place の更新だけ（文言の差。astro ではルールの description が英語の文言に、Lambda に `PROJECT_NAME` が加わる）
+3. 確認のうえ apply。旧モジュールのディレクトリを消す
+
+詳細と実機の確認は [ADR 0006](../../docs/adr/0006-library-owns-table-operations.md) の段階 6。

package/terraform/alerts-cleanup/main.tf

@@ -0,0 +1,111 @@
+# 運用通知の記録（alerts）の定時削除（ADR 0003・ADR 0006 の (b)。docs/NOTIFY.md の「削除（定時 Lambda）」）
+# 最後の発生から 28 日を過ぎた alerts を、定時に消す（ネイティブ TTL は効かない）。
+# Lambda の成果物はアプリが作り、source_file で渡す（実装は `createAlertsCleanupHandler`）。
+#
+# 失敗は構造化ログ（error）に出す。このロググループは、通知（../ops-notify）に購読させる。
+# リソースのアドレス・名前は、asanowa / astro の旧モジュール（infra/modules/alerts-cleanup）と同じ。
+
+locals {
+  prefix = "${var.project_name}-${var.environment}"
+}
+
+data "archive_file" "cleanup" {
+  type        = "zip"
+  source_file = var.source_file
+  output_path = "${path.root}/.terraform/archives/alerts-cleanup.zip"
+}
+
+resource "aws_cloudwatch_log_group" "cleanup" {
+  name              = "/aws/lambda/${local.prefix}-alerts-cleanup"
+  retention_in_days = var.log_retention_days
+}
+
+resource "aws_iam_role" "cleanup" {
+  name = "${local.prefix}-alerts-cleanup-role"
+
+  assume_role_policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [{
+      Action    = "sts:AssumeRole"
+      Effect    = "Allow"
+      Principal = { Service = "lambda.amazonaws.com" }
+    }]
+  })
+}
+
+resource "aws_iam_role_policy_attachment" "cleanup_logs" {
+  role       = aws_iam_role.cleanup.name
+  policy_arn = "arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole"
+}
+
+# Records Lambda の IAM 認証版 URL（エイリアス）を呼ぶ権限だけ（最小権限）。DynamoDB には直接触れない
+resource "aws_iam_role_policy" "cleanup_invoke_records" {
+  name = "${local.prefix}-alerts-cleanup-invoke-records"
+  role = aws_iam_role.cleanup.id
+
+  policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [{
+      Effect   = "Allow"
+      Action   = ["lambda:InvokeFunctionUrl"]
+      Resource = [var.records_iam_alias_arn]
+    }]
+  })
+}
+
+resource "aws_lambda_function" "cleanup" {
+  function_name    = "${local.prefix}-alerts-cleanup"
+  role             = aws_iam_role.cleanup.arn
+  filename         = data.archive_file.cleanup.output_path
+  source_code_hash = data.archive_file.cleanup.output_base64sha256
+  handler          = var.handler
+  runtime          = "nodejs22.x"
+  architectures    = ["arm64"]
+  timeout          = 120
+  memory_size      = 256
+
+  environment {
+    # PROJECT_NAME は createAlertsCleanupHandler の app の既定（app を渡すアプリは読まない）
+    variables = {
+      PROJECT_NAME    = var.project_name
+      RECORDS_IAM_URL = var.records_iam_function_url
+    }
+  }
+
+  logging_config {
+    log_format = "JSON"
+    log_group  = aws_cloudwatch_log_group.cleanup.name
+  }
+
+  depends_on = [aws_iam_role_policy_attachment.cleanup_logs]
+}
+
+# 再試行は 0（翌日の定時実行で残りを消す。失敗はログ → 通知で知る）
+resource "aws_lambda_function_event_invoke_config" "cleanup" {
+  function_name          = aws_lambda_function.cleanup.function_name
+  maximum_retry_attempts = 0
+}
+
+resource "aws_cloudwatch_event_rule" "cleanup" {
+  name                = "${local.prefix}-alerts-cleanup"
+  description         = "Delete ops alerts records older than 28 days (daily 03:00 JST)"
+  schedule_expression = var.schedule_expression
+}
+
+resource "aws_cloudwatch_event_target" "cleanup" {
+  rule = aws_cloudwatch_event_rule.cleanup.name
+  arn  = aws_lambda_function.cleanup.arn
+
+  retry_policy {
+    maximum_retry_attempts       = 0
+    maximum_event_age_in_seconds = 3600
+  }
+}
+
+resource "aws_lambda_permission" "cleanup_events" {
+  statement_id  = "AllowEventBridgeInvoke"
+  action        = "lambda:InvokeFunction"
+  function_name = aws_lambda_function.cleanup.function_name
+  principal     = "events.amazonaws.com"
+  source_arn    = aws_cloudwatch_event_rule.cleanup.arn
+}