@dsh-cc/settings-migrations 0.5.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/settings/settings-migrations/README.md
+README.md: 0b6a83bf901d2dcc5d114d646e0e3386fb779657
+README.zh.md: 8775b046dcecb51630282bec43b56c1eae65abc4

package/README.md

@@ -0,0 +1,76 @@
+# @dsh-cc/settings-migrations
+
+English | [中文](README.zh.md)
+
+Claude Code-style settings migration mechanism for the DeepSeek Harness. A versioned `defineMigration` list is applied by `runMigrations()` against an atomically-written `settings.json`, mirroring CC's run-at-startup migrations. The bundled plugin auto-runs pending migrations on mount without ever taking down the host.
+
+## Status: mechanism ready, no real migrations yet
+
+This batch ships the machinery but **no concrete migrations** — neither cc nor dsh has a legacy settings format to migrate. The first real migration will land with the first settings-shape change (for example a renamed or removed key). Until then the registry is empty and mounting the plugin is a no-op.
+
+## Mechanism
+
+```ts
+import { defineMigration, runMigrations, readMigrationState } from '@dsh-cc/settings-migrations'
+
+defineMigration({
+  version: 1,
+  name: 'rename-field',
+  migrate: (ctx) => {
+    ctx.settings.theme = ctx.settings['ui-theme']   // mutate the raw settings doc
+    delete ctx.settings['ui-theme']
+  },
+})
+
+await runMigrations()   // applies every registered migration
+```
+
+- **`defineMigration({ version, name, migrate(ctx) })`** registers a migration into the module registry (deduplicated by `version` + `name`). `ctx.settings` is the mutable raw JSON document; a migration rewrites it in place.
+- **`runMigrations(migrations?, options?)`** applies every migration whose `version` exceeds the recorded `migrationVersion`, in ascending version order. Pass an explicit list for tests/direct invocation, or omit it to use the registry. Options: `home` (harness home), `settingsPath`, `statePath`.
+- **`readMigrationState(statePath)`** returns `{ migrationVersion }`, defaulting to `0` when the state file is absent.
+
+## Version storage
+
+The recorded version lives in a **dedicated state file** in the harness home (resolved via the harness home-paths tooling — `$DSH_HOME` or `~/.dsh`), defaulting to `<home>/migrations.json`; the settings document defaults to `<home>/settings.json`. The state shape is `{ "migrationVersion": N }`. Both locations are overridable per run / per plugin config for tests and constrained deployments.
+
+## Semantics (the contract)
+
+- **Ascending version order.** pending = migrations with `version > migrationVersion`, sorted low to high.
+- **Whole-batch atomicity.** The batch succeeds only when every pending migration completes; the version then advances to the latest pending version. A single throw aborts the run: nothing is written and the version stays put, so the next run re-attempts the failing survivors.
+- **Migrations must be idempotent.** Because a mid-batch failure leaves the version behind, earlier migrations in the batch may run again on the next attempt (and CC's startup runner re-runs the whole set). Write your migration so running it twice is harmless — CC's own migrations encode a self-guard on the source data for exactly this reason.
+- **`guard` skips without blocking.** A `guard(ctx)` returning `false` skips that migration but still counts as success for version advancement (CC treats a skipped run as completing the set). A `guard` returning `true` runs the migration.
+- **Atomic write path.** Settings and state are written via a sibling temp file then `rename`, so a reader never observes a partially-written document and no temp files are left behind.
+
+## Plugin
+
+`name`, `Config`, `apply(ctx, config)`:
+
+```ts
+await ctx.plugin(SettingsMigrations, { dshHome, autoRunOnMount: true })
+```
+
+| Config | Meaning | Default |
+|---|---|---|
+| `dshHome` | Harness home for the default paths | `$DSH_HOME` or `~/.dsh` |
+| `settingsPath` | `settings.json` override | `<home>/settings.json` |
+| `statePath` | migration state file override | `<home>/migrations.json` |
+| `autoRunOnMount` | run pending migrations on mount | `true` |
+
+Mounting runs pending registered migrations (equivalent to CC running migrations at startup). A failed batch never takes down the host: the error is logged as a warning and the recorded version is retained so the next mount re-attempts the survivors.
+
+## Install / registration
+
+```ts
+import * as SettingsMigrations from '@dsh-cc/settings-migrations'
+await ctx.plugin(SettingsMigrations)
+```
+
+## Build order
+
+`settings-migrations` depends on the harness base packages (`@deepseek-ai/cordis`, `@deepseek-ai/schemastery`, `@deepseek-ai/dsh-home-paths`, `@deepseek-ai/dsh-invariants`) and no workspace package, so it builds as soon as those are available.
+
+## Known limitations
+
+- **Mechanism only.** No migrations ship yet; seeding them for local verification is the owner's call per environment.
+- **Single settings document.** The runner targets the user `settings.json`; project/local/flag layers (see `settings-cascade`) are not yet migration targets.
+- **Best-effort failure report.** The plugin warns and retains the version on failure; it does not surface a structured migration report to the seam.

package/README.zh.md

@@ -0,0 +1,76 @@
+# @dsh-cc/settings-migrations
+
+[English](README.md) | 中文
+
+面向 DeepSeek Harness 的 Claude Code 式设置迁移机制。`defineMigration` 定义一个带版本号的迁移，`runMigrations()` 对原子写入的 `settings.json` 应用迁移，对齐 CC 启动时运行的 migration。打包的插件在挂载时自动运行待办迁移，且绝不让宿主崩溃。
+
+## 状态：机制就绪，尚无真实迁移
+
+本批只交付机制，**不落地具体迁移** —— cc/dsh 目前都没有旧版设置格式需要迁移。首个真实迁移将随首个 settings 格式变更（例如更名或删除某个键）落地。在此之前注册表为空，挂载插件是一个空操作。
+
+## 机制
+
+```ts
+import { defineMigration, runMigrations, readMigrationState } from '@dsh-cc/settings-migrations'
+
+defineMigration({
+  version: 1,
+  name: 'rename-field',
+  migrate: (ctx) => {
+    ctx.settings.theme = ctx.settings['ui-theme']   // 原地改写原始 settings 文档
+    delete ctx.settings['ui-theme']
+  },
+})
+
+await runMigrations()   // 应用所有已注册迁移
+```
+
+- **`defineMigration({ version, name, migrate(ctx) })`** 将迁移注册进模块注册表（按 `version` + `name` 去重）。`ctx.settings` 是可变的原始 JSON 文档，迁移在其中原地改写。
+- **`runMigrations(migrations?, options?)`** 应用所有 `version` 大于已记录 `migrationVersion` 的迁移，按版本升序。测试/直调可传入显式列表，省略则使用注册表。选项：`home`（harness 家目录）、`settingsPath`、`statePath`。
+- **`readMigrationState(statePath)`** 返回 `{ migrationVersion }`，状态文件缺失时默认 `0`。
+
+## 版本存储
+
+已记录版本存放在 harness 家目录下的**独立状态文件**里（经 harness 的 home-paths 工具解析——`$DSH_HOME` 或 `~/.dsh`），默认 `<home>/migrations.json`；settings 文档默认 `<home>/settings.json`。状态形如 `{ "migrationVersion": N }`。测试或受限部署可按次运行/按插件配置覆盖这两个位置。
+
+## 语义（即契约）
+
+- **版本升序。** 待办 = 满足 `version > migrationVersion` 的迁移，低到高排序。
+- **整批原子性。** 仅当所有待办迁移都完成，批次才算成功，随后版本推进到最新待办版本。任一次抛错即中止运行：不写任何内容、版本保持不变，下次运行会重试失败的幸存者。
+- **迁移器必须幂等。** 因为批次中途失败会留下旧版本，批次中较早的迁移在下次尝试时会再次运行（CC 的启动运行器同样会重跑整套）。请把迁移写成“跑两次也无害”——CC 自身正是为此在源数据上编码了自守条件。
+- **`guard` 跳过不阻塞版本。** `guard(ctx)` 返回 `false` 会跳过该迁移，但仍被当作成功计入版本推进（CC 把跳过视为完成整套）。返回 `true` 则执行迁移。
+- **原子写路径。** settings 与状态均通过同级临时文件再 `rename` 写入，读取方永远不会看到半写文档，也不会残留临时文件。
+
+## 插件
+
+`name`、`Config`、`apply(ctx, config)`：
+
+```ts
+await ctx.plugin(SettingsMigrations, { dshHome, autoRunOnMount: true })
+```
+
+| Config | 含义 | 默认 |
+|---|---|---|
+| `dshHome` | 用于默认路径的 harness 家目录 | `$DSH_HOME` 或 `~/.dsh` |
+| `settingsPath` | `settings.json` 覆盖 | `<home>/settings.json` |
+| `statePath` | 迁移状态文件覆盖 | `<home>/migrations.json` |
+| `autoRunOnMount` | 挂载时运行待办迁移 | `true` |
+
+挂载即运行待办已注册迁移（等价于 CC 启动时运行迁移）。失败的批次绝不会让宿主崩溃：错误仅记录为警告并保留已记录版本，下次挂载重试幸存者。
+
+## 安装 / 注册
+
+```ts
+import * as SettingsMigrations from '@dsh-cc/settings-migrations'
+await ctx.plugin(SettingsMigrations)
+```
+
+## 构建顺序
+
+`settings-migrations` 只依赖 harness 基础包（`@deepseek-ai/cordis`、`@deepseek-ai/schemastery`、`@deepseek-ai/dsh-home-paths`、`@deepseek-ai/dsh-invariants`），不依赖任何 workspace 包，这些就绪即可构建。
+
+## 已知限制
+
+- **仅机制。** 尚未携带任何迁移；是否植入用于本地验证的迁移由各环境自行决定。
+- **单份 settings 文档。** 运行器只针对用户 `settings.json`；project/local/flag 各层（见 `settings-cascade`）暂不是迁移目标。
+- **尽力而为的失败上报。** 失败时插件只警告并保留版本，不向 seam 上报结构化的迁移报告。

package/lib/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Claude Code-style settings migration plugin. On mount it runs every registered
+ * migration whose version exceeds the recorded `migrationVersion`, mirroring CC's
+ * run-at-startup behavior. A failed batch never takes down the host: the error is
+ * logged as a warning and the recorded version is retained so the next mount
+ * re-attempts the survivors. The mechanism itself — `defineMigration`,
+ * `runMigrations`, `readMigrationState` — is exported for direct invocation.
+ *
+ * This batch ships no real migrations: cc/dsh has no legacy format to migrate yet.
+ * The first concrete migration will land with the first settings-shape change.
+ * @module @dsh-cc/settings-migrations
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+export { DEFAULT_STATE_FILENAME, defineMigration, listMigrations, readMigrationState, runMigrations, type MigrateOptions, type Migration, type MigrationContext, type MigrationState, } from './migrate.ts';
+/** Cordis plugin id. */
+export declare const name = "settings-migrations";
+/** Plugin configuration: file locations and the auto-run switch. */
+export interface Config {
+    /** Harness home used to derive the default settings/state paths. */
+    dshHome?: string;
+    /** `settings.json` path override (defaults to `<home>/settings.json`). */
+    settingsPath?: string;
+    /** Migration state path override (defaults to `<home>/migrations.json`). */
+    statePath?: string;
+    /** Run pending migrations on mount. Defaults to true (CC runs at startup). */
+    autoRunOnMount?: boolean;
+}
+/** Runtime config schema (all fields optional). */
+export declare const Config: z<Config>;
+/**
+ * Mount the migration runner. With `autoRunOnMount` (the default) pending
+ * registered migrations run against the resolved settings/state paths; a failure
+ * warms but never crashes the host and retains the recorded version.
+ * @param ctx - the plug context.
+ * @param config - plugin configuration.
+ */
+export declare function apply(ctx: Context, config?: Config): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,CAAC,MAAM,0BAA0B,CAAA;AAGxC,OAAO,EACL,sBAAsB,EACtB,eAAe,EACf,cAAc,EACd,kBAAkB,EAClB,aAAa,EACb,KAAK,cAAc,EACnB,KAAK,SAAS,EACd,KAAK,gBAAgB,EACrB,KAAK,cAAc,GACpB,MAAM,cAAc,CAAA;AAErB,wBAAwB;AACxB,eAAO,MAAM,IAAI,wBAAwB,CAAA;AAEzC,oEAAoE;AACpE,MAAM,WAAW,MAAM;IACrB,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,0EAA0E;IAC1E,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,8EAA8E;IAC9E,cAAc,CAAC,EAAE,OAAO,CAAA;CACzB;AAED,mDAAmD;AACnD,eAAO,MAAM,MAAM,EAAE,CAAC,CAAC,MAAM,CAK3B,CAAA;AAEF;;;;;;GAMG;AACH,wBAAsB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,GAAE,MAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAa5E"}

package/lib/index.js

@@ -0,0 +1,51 @@
+/**
+ * Claude Code-style settings migration plugin. On mount it runs every registered
+ * migration whose version exceeds the recorded `migrationVersion`, mirroring CC's
+ * run-at-startup behavior. A failed batch never takes down the host: the error is
+ * logged as a warning and the recorded version is retained so the next mount
+ * re-attempts the survivors. The mechanism itself — `defineMigration`,
+ * `runMigrations`, `readMigrationState` — is exported for direct invocation.
+ *
+ * This batch ships no real migrations: cc/dsh has no legacy format to migrate yet.
+ * The first concrete migration will land with the first settings-shape change.
+ * @module @dsh-cc/settings-migrations
+ */
+import z from '@deepseek-ai/schemastery';
+import { listMigrations, runMigrations } from "./migrate.js";
+export { DEFAULT_STATE_FILENAME, defineMigration, listMigrations, readMigrationState, runMigrations, } from "./migrate.js";
+/** Cordis plugin id. */
+export const name = 'settings-migrations';
+/** Runtime config schema (all fields optional). */
+export const Config = z.object({
+    dshHome: z.string(),
+    settingsPath: z.string(),
+    statePath: z.string(),
+    autoRunOnMount: z.boolean(),
+});
+/**
+ * Mount the migration runner. With `autoRunOnMount` (the default) pending
+ * registered migrations run against the resolved settings/state paths; a failure
+ * warms but never crashes the host and retains the recorded version.
+ * @param ctx - the plug context.
+ * @param config - plugin configuration.
+ */
+export async function apply(ctx, config = {}) {
+    if (config.autoRunOnMount === false)
+        return;
+    const options = {};
+    if (config.dshHome !== undefined)
+        options.home = config.dshHome;
+    if (config.settingsPath !== undefined)
+        options.settingsPath = config.settingsPath;
+    if (config.statePath !== undefined)
+        options.statePath = config.statePath;
+    try {
+        const state = await runMigrations(listMigrations(), options);
+        ctx.logger.info(`settings-migrations: at migrationVersion ${state.migrationVersion}`);
+    }
+    catch (error) {
+        // A failed batch must never take down the host: warn and retain the version.
+        ctx.logger.warn(`settings-migrations: batch failed, version retained: ${String(error)}`);
+    }
+}
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,CAAC,MAAM,0BAA0B,CAAA;AACxC,OAAO,EAAE,cAAc,EAAE,aAAa,EAAuB,MAAM,cAAc,CAAA;AAEjF,OAAO,EACL,sBAAsB,EACtB,eAAe,EACf,cAAc,EACd,kBAAkB,EAClB,aAAa,GAKd,MAAM,cAAc,CAAA;AAErB,wBAAwB;AACxB,MAAM,CAAC,MAAM,IAAI,GAAG,qBAAqB,CAAA;AAczC,mDAAmD;AACnD,MAAM,CAAC,MAAM,MAAM,GAAc,CAAC,CAAC,MAAM,CAAC;IACxC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE;IACxB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,cAAc,EAAE,CAAC,CAAC,OAAO,EAAE;CAC5B,CAAC,CAAA;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,KAAK,CAAC,GAAY,EAAE,SAAiB,EAAE;IAC3D,IAAI,MAAM,CAAC,cAAc,KAAK,KAAK;QAAE,OAAM;IAC3C,MAAM,OAAO,GAAmB,EAAE,CAAA;IAClC,IAAI,MAAM,CAAC,OAAO,KAAK,SAAS;QAAE,OAAO,CAAC,IAAI,GAAG,MAAM,CAAC,OAAO,CAAA;IAC/D,IAAI,MAAM,CAAC,YAAY,KAAK,SAAS;QAAE,OAAO,CAAC,YAAY,GAAG,MAAM,CAAC,YAAY,CAAA;IACjF,IAAI,MAAM,CAAC,SAAS,KAAK,SAAS;QAAE,OAAO,CAAC,SAAS,GAAG,MAAM,CAAC,SAAS,CAAA;IACxE,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,MAAM,aAAa,CAAC,cAAc,EAAE,EAAE,OAAO,CAAC,CAAA;QAC5D,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,4CAA4C,KAAK,CAAC,gBAAgB,EAAE,CAAC,CAAA;IACvF,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,6EAA6E;QAC7E,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,wDAAwD,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;IAC1F,CAAC;AACH,CAAC"}

package/lib/migrate.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Claude Code-style settings migration mechanism. `defineMigration()` registers a
+ * versioned, named migration; `runMigrations()` applies every registered migration
+ * whose version exceeds the recorded `migrationVersion`, in ascending order, against
+ * an atomically-written `settings.json`.
+ *
+ * The whole batch succeeds only when every pending migration completes: a single
+ * throw keeps the old recorded version and leaves the settings document untouched,
+ * so the next run re-attempts the failing survivors. A guard returning `false`
+ * skips a migration without blocking version advancement (mirroring Claude Code).
+ * Migrations MUST be idempotent — see the README for the contract.
+ * @module @dsh-cc/settings-migrations
+ */
+/** A migration mutates the raw settings document in place via `ctx.settings`. */
+export interface MigrationContext {
+    /** The mutable raw settings document shared across the running batch. */
+    settings: Record<string, unknown>;
+}
+/** One versioned, named migration in the Claude Code style. */
+export interface Migration {
+    /** Monotonic version; migrations run in ascending version order. */
+    version: number;
+    /** Human-readable name, surfaced in logs and errors. */
+    name: string;
+    /** Optional self-guard; a `false` return skips the migration without blocking the batch. */
+    guard?(ctx: MigrationContext): boolean | Promise<boolean>;
+    /** Apply the migration by mutating `ctx.settings` (must be idempotent). */
+    migrate(ctx: MigrationContext): void | Promise<void>;
+}
+/** Recorded migration state document. */
+export interface MigrationState {
+    /** The highest migration version whose batch has fully applied. */
+    migrationVersion: number;
+}
+/** Options controlling the default file locations for a migration run. */
+export interface MigrateOptions {
+    /** Harness home used to derive the default settings/state paths. */
+    home?: string;
+    /** `settings.json` path; defaults to `<home>/settings.json`. */
+    settingsPath?: string;
+    /** Migration state file path; defaults to `<home>/migrations.json`. */
+    statePath?: string;
+}
+/** Default migration-state filename inside the harness home. */
+export declare const DEFAULT_STATE_FILENAME = "migrations.json";
+/** Read the recorded migration state; an absent file yields version 0. */
+export declare function readMigrationState(statePath: string): Promise<MigrationState>;
+/**
+ * Register a migration into the module-level registry, deduplicated by
+ * `version` + `name` so re-registration is idempotent. Returns the migration.
+ */
+export declare function defineMigration(migration: Migration): Migration;
+/** Snapshot of the currently registered migrations, ascending by version. */
+export declare function listMigrations(): Migration[];
+/**
+ * Apply every migration whose version exceeds the recorded `migrationVersion`, in
+ * ascending order, against the settings document. The batch succeeds only when all
+ * pending migrations complete (a guard-`false` skip counts as success and does not
+ * block version advancement). On success the possibly-mutated settings document is
+ * written atomically and the recorded version advances to the latest pending version.
+ * A single throw aborts the batch: nothing is written and the version stays put, so
+ * the next run re-attempts the failing survivors.
+ * @param migrations - the migrations to consider; a snapshot of the registry when omitted.
+ * @param options - optional file-location overrides.
+ * @returns the recorded state after the run (unchanged when nothing was pending).
+ */
+export declare function runMigrations(migrations?: readonly Migration[], options?: MigrateOptions): Promise<MigrationState>;
+//# sourceMappingURL=migrate.d.ts.map

package/lib/migrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../src/migrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH,iFAAiF;AACjF,MAAM,WAAW,gBAAgB;IAC/B,yEAAyE;IACzE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAClC;AAED,+DAA+D;AAC/D,MAAM,WAAW,SAAS;IACxB,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAA;IACf,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAA;IACZ,4FAA4F;IAC5F,KAAK,CAAC,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IACzD,2EAA2E;IAC3E,OAAO,CAAC,GAAG,EAAE,gBAAgB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACrD;AAED,yCAAyC;AACzC,MAAM,WAAW,cAAc;IAC7B,mEAAmE;IACnE,gBAAgB,EAAE,MAAM,CAAA;CACzB;AAED,0EAA0E;AAC1E,MAAM,WAAW,cAAc;IAC7B,oEAAoE;IACpE,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,gEAAgE;IAChE,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,gEAAgE;AAChE,eAAO,MAAM,sBAAsB,oBAAoB,CAAA;AA8BvD,0EAA0E;AAC1E,wBAAsB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAInF;AAoBD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,SAAS,GAAG,SAAS,CAK/D;AAED,6EAA6E;AAC7E,wBAAgB,cAAc,IAAI,SAAS,EAAE,CAE5C;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CACjC,UAAU,CAAC,EAAE,SAAS,SAAS,EAAE,EACjC,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,cAAc,CAAC,CAoBzB"}

package/lib/migrate.js

@@ -0,0 +1,118 @@
+/**
+ * Claude Code-style settings migration mechanism. `defineMigration()` registers a
+ * versioned, named migration; `runMigrations()` applies every registered migration
+ * whose version exceeds the recorded `migrationVersion`, in ascending order, against
+ * an atomically-written `settings.json`.
+ *
+ * The whole batch succeeds only when every pending migration completes: a single
+ * throw keeps the old recorded version and leaves the settings document untouched,
+ * so the next run re-attempts the failing survivors. A guard returning `false`
+ * skips a migration without blocking version advancement (mirroring Claude Code).
+ * Migrations MUST be idempotent — see the README for the contract.
+ * @module @dsh-cc/settings-migrations
+ */
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { resolveDshHome } from '@deepseek-ai/dsh-home-paths';
+/** Default migration-state filename inside the harness home. */
+export const DEFAULT_STATE_FILENAME = 'migrations.json';
+/** Registry of migrations contributed via {@link defineMigration}. */
+const registry = [];
+function isENOENT(error) {
+    return error?.code === 'ENOENT';
+}
+/** Resolve the settings/state paths, defaulting both from the harness home. */
+function resolveOptions(options = {}) {
+    const home = resolveDshHome(options.home);
+    return {
+        settingsPath: options.settingsPath ?? join(home, 'settings.json'),
+        statePath: options.statePath ?? join(home, DEFAULT_STATE_FILENAME),
+    };
+}
+/** Read a JSON file, returning `undefined` when it is absent. */
+async function readJson(path) {
+    let text;
+    try {
+        text = await readFile(path, 'utf8');
+    }
+    catch (error) {
+        if (isENOENT(error))
+            return undefined;
+        throw error;
+    }
+    return JSON.parse(text);
+}
+/** Read the recorded migration state; an absent file yields version 0. */
+export async function readMigrationState(statePath) {
+    const state = await readJson(statePath);
+    const version = typeof state?.migrationVersion === 'number' ? state.migrationVersion : 0;
+    return { migrationVersion: version };
+}
+/** Read the raw settings document; an absent file yields an empty object. */
+async function readSettingsDocument(path) {
+    const doc = await readJson(path);
+    if (doc === undefined)
+        return {};
+    if (typeof doc !== 'object' || doc === null || Array.isArray(doc)) {
+        throw new TypeError(`settings-migrations: ${path} must be a JSON object`);
+    }
+    return doc;
+}
+/** Write a file atomically: write to a sibling temp path, then rename into place. */
+async function writeJsonAtomic(path, value) {
+    await mkdir(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp`;
+    await writeFile(tmp, JSON.stringify(value, null, 2), 'utf8');
+    await rename(tmp, path);
+}
+/**
+ * Register a migration into the module-level registry, deduplicated by
+ * `version` + `name` so re-registration is idempotent. Returns the migration.
+ */
+export function defineMigration(migration) {
+    const index = registry.findIndex(m => m.version === migration.version && m.name === migration.name);
+    if (index === -1)
+        registry.push(migration);
+    else
+        registry[index] = migration;
+    return migration;
+}
+/** Snapshot of the currently registered migrations, ascending by version. */
+export function listMigrations() {
+    return [...registry].sort((a, b) => a.version - b.version);
+}
+/**
+ * Apply every migration whose version exceeds the recorded `migrationVersion`, in
+ * ascending order, against the settings document. The batch succeeds only when all
+ * pending migrations complete (a guard-`false` skip counts as success and does not
+ * block version advancement). On success the possibly-mutated settings document is
+ * written atomically and the recorded version advances to the latest pending version.
+ * A single throw aborts the batch: nothing is written and the version stays put, so
+ * the next run re-attempts the failing survivors.
+ * @param migrations - the migrations to consider; a snapshot of the registry when omitted.
+ * @param options - optional file-location overrides.
+ * @returns the recorded state after the run (unchanged when nothing was pending).
+ */
+export async function runMigrations(migrations, options) {
+    const list = migrations ?? listMigrations();
+    const { settingsPath, statePath } = resolveOptions(options);
+    const settings = await readSettingsDocument(settingsPath);
+    const state = await readMigrationState(statePath);
+    const pending = list
+        .filter(m => m.version > state.migrationVersion)
+        .sort((a, b) => a.version - b.version);
+    if (pending.length === 0)
+        return state;
+    const context = { settings };
+    for (const migration of pending) {
+        if (migration.guard !== undefined && !(await migration.guard(context)))
+            continue;
+        await migration.migrate(context);
+    }
+    const latest = pending[pending.length - 1].version;
+    const next = { migrationVersion: latest };
+    await writeJsonAtomic(settingsPath, settings);
+    await writeJsonAtomic(statePath, next);
+    return next;
+}
+//# sourceMappingURL=migrate.js.map

package/lib/migrate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.js","sourceRoot":"","sources":["../src/migrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AACrE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAA;AAoC5D,gEAAgE;AAChE,MAAM,CAAC,MAAM,sBAAsB,GAAG,iBAAiB,CAAA;AAEvD,sEAAsE;AACtE,MAAM,QAAQ,GAAgB,EAAE,CAAA;AAEhC,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAQ,KAAsC,EAAE,IAAI,KAAK,QAAQ,CAAA;AACnE,CAAC;AAED,+EAA+E;AAC/E,SAAS,cAAc,CAAC,UAA0B,EAAE;IAClD,MAAM,IAAI,GAAG,cAAc,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;IACzC,OAAO;QACL,YAAY,EAAE,OAAO,CAAC,YAAY,IAAI,IAAI,CAAC,IAAI,EAAE,eAAe,CAAC;QACjE,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,IAAI,CAAC,IAAI,EAAE,sBAAsB,CAAC;KACnE,CAAA;AACH,CAAC;AAED,iEAAiE;AACjE,KAAK,UAAU,QAAQ,CAAI,IAAY;IACrC,IAAI,IAAY,CAAA;IAChB,IAAI,CAAC;QACH,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;IACrC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,QAAQ,CAAC,KAAK,CAAC;YAAE,OAAO,SAAS,CAAA;QACrC,MAAM,KAAK,CAAA;IACb,CAAC;IACD,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAM,CAAA;AAC9B,CAAC;AAED,0EAA0E;AAC1E,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,SAAiB;IACxD,MAAM,KAAK,GAAG,MAAM,QAAQ,CAAiB,SAAS,CAAC,CAAA;IACvD,MAAM,OAAO,GAAG,OAAO,KAAK,EAAE,gBAAgB,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAA;IACxF,OAAO,EAAE,gBAAgB,EAAE,OAAO,EAAE,CAAA;AACtC,CAAC;AAED,6EAA6E;AAC7E,KAAK,UAAU,oBAAoB,CAAC,IAAY;IAC9C,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAU,IAAI,CAAC,CAAA;IACzC,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,EAAE,CAAA;IAChC,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QAClE,MAAM,IAAI,SAAS,CAAC,wBAAwB,IAAI,wBAAwB,CAAC,CAAA;IAC3E,CAAC;IACD,OAAO,GAA8B,CAAA;AACvC,CAAC;AAED,qFAAqF;AACrF,KAAK,UAAU,eAAe,CAAC,IAAY,EAAE,KAAc;IACzD,MAAM,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;IAC/C,MAAM,GAAG,GAAG,GAAG,IAAI,MAAM,CAAA;IACzB,MAAM,SAAS,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,CAAA;IAC5D,MAAM,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,CAAA;AACzB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,SAAoB;IAClD,MAAM,KAAK,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,SAAS,CAAC,OAAO,IAAI,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC,IAAI,CAAC,CAAA;IACnG,IAAI,KAAK,KAAK,CAAC,CAAC;QAAE,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,CAAA;;QACrC,QAAQ,CAAC,KAAK,CAAC,GAAG,SAAS,CAAA;IAChC,OAAO,SAAS,CAAA;AAClB,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,cAAc;IAC5B,OAAO,CAAC,GAAG,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC,CAAA;AAC5D,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,UAAiC,EACjC,OAAwB;IAExB,MAAM,IAAI,GAAG,UAAU,IAAI,cAAc,EAAE,CAAA;IAC3C,MAAM,EAAE,YAAY,EAAE,SAAS,EAAE,GAAG,cAAc,CAAC,OAAO,CAAC,CAAA;IAC3D,MAAM,QAAQ,GAAG,MAAM,oBAAoB,CAAC,YAAY,CAAC,CAAA;IACzD,MAAM,KAAK,GAAG,MAAM,kBAAkB,CAAC,SAAS,CAAC,CAAA;IACjD,MAAM,OAAO,GAAG,IAAI;SACjB,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,GAAG,KAAK,CAAC,gBAAgB,CAAC;SAC/C,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC,CAAA;IACxC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAA;IAEtC,MAAM,OAAO,GAAqB,EAAE,QAAQ,EAAE,CAAA;IAC9C,KAAK,MAAM,SAAS,IAAI,OAAO,EAAE,CAAC;QAChC,IAAI,SAAS,CAAC,KAAK,KAAK,SAAS,IAAI,CAAC,CAAC,MAAM,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YAAE,SAAQ;QAChF,MAAM,SAAS,CAAC,OAAO,CAAC,OAAO,CAAC,CAAA;IAClC,CAAC;IACD,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAE,CAAC,OAAO,CAAA;IACnD,MAAM,IAAI,GAAmB,EAAE,gBAAgB,EAAE,MAAM,EAAE,CAAA;IACzD,MAAM,eAAe,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAA;IAC7C,MAAM,eAAe,CAAC,SAAS,EAAE,IAAI,CAAC,CAAA;IACtC,OAAO,IAAI,CAAA;AACb,CAAC"}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@dsh-cc/settings-migrations",
+  "description": "Claude Code-style settings migration mechanism for the DeepSeek Harness: defineMigration list, version-gated runMigrations, and an atomic read/write settings.json seam",
+  "version": "0.5.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dsh-cc/dsh-cc.git",
+    "directory": "packages/settings/settings-migrations"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib"
+  ],
+  "license": "Apache-2.0",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-home-paths": ">=0.1.1-rc.2",
+    "@deepseek-ai/dsh-invariants": ">=0.1.1-rc.2",
+    "@deepseek-ai/cordis": ">=0.1.1-rc.2",
+    "@deepseek-ai/schemastery": ">=0.1.1-rc.2"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-home-paths": "link:../../../../deepseek-harness/packages/util/home-paths",
+    "@deepseek-ai/dsh-invariants": "link:../../../../deepseek-harness/packages/runtime-diagnostics/invariants",
+    "@deepseek-ai/cordis": "link:../../../../deepseek-harness/vendor/cordis",
+    "@deepseek-ai/schemastery": "link:../../../../deepseek-harness/vendor/schemastery"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}