@deepseek-ai/dsh-fs-patch 0.0.0-stage → 0.2.2-alpha.3

package/LICENSE

@@ -0,0 +1,235 @@
+DeepSeek contributions are licensed under MIT below.
+
+This package adapts patch parsing and text updates from OpenAI Codex
+rust-v0.158.0 (codex-rs/apply-patch/src/parser.rs, streaming_parser.rs,
+seek_sequence.rs, and file_update.rs), with text_file.rs as a reference
+for the line-ending representations. Test fixtures also draw from
+file_update_tests.rs and lib.rs in that directory.
+Copyright 2025 OpenAI. Those portions remain under Apache License 2.0 below.
+Modifications: pure TypeScript batch API, original-input line locations,
+serializable records, explicit rejection of environment-routing headers,
+and a filesystem-independent NormalizeToLf updater with structured failures.
+Selected parser and text tests are adapted from the same Apache-licensed sources.
+
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+                                 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 2025 OpenAI
+
+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,40 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/fs/fs-patch/README.md
+/:
+  en: 80da396fec6cc3d9
+  zh: 35d4d8c713d9450c
+/dsh-fs-patch:
+  en: ad2970c594c3b669
+  zh: fee247cad74b6191
+/dsh-fs-patch/summary:
+  en: 614121759671f168
+  zh: 7cea460bb8940793
+/dsh-fs-patch/table-of-contents:
+  en: 170f124543e5647a
+  zh: c30de483a11a1c09
+/dsh-fs-patch/use-this-package:
+  en: 142b3b023512fc72
+  zh: bcfa70b710947eaf
+/dsh-fs-patch/compatibility:
+  en: 70da6aede0649b32
+  zh: 2e3ed2964ae0461a
+/dsh-fs-patch/compatibility/parsing:
+  en: 06644a9c38f7d569
+  zh: 91ca563d4e789087
+/dsh-fs-patch/compatibility/matching-and-text-updates:
+  en: fcd630c121472565
+  zh: 35cc062e2f76b195
+/dsh-fs-patch/understand-the-implementation:
+  en: 2ded4719a85a20bc
+  zh: e04f2614167a6c1c
+/dsh-fs-patch/further-exploration:
+  en: d7d750bd71805956
+  zh: 8d33c76f5895d286
+/dsh-fs-patch/known-limitations-and-deferred-work:
+  en: b18ead2791224bc2
+  zh: a4a8ab319c072445
+/dsh-fs-patch/known-limitations-and-deferred-work/dev-note:
+  en: e67f633dc6fe7773
+  zh: e88aeb617ffb74ea

package/README.md

@@ -1,3 +1,112 @@
-# Temporary Holding Version
+---
+description: "Parse Codex-style patches and apply hunks to text without filesystem I/O."
+kind: "package-library"
+---
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# dsh-fs-patch
+
+English | [中文](README.zh.md)
+
+## Summary
+
+Parse a complete Codex-style patch into ordered file operations with `parsePatch`, then apply update hunks to LF-normalized text with `applyHunks`. Both functions work on caller-supplied strings without filesystem access. Syntax errors throw with the original input line; matching returns new text or a structured failure.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Compatibility](#compatibility)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+<a id="use-this-package"></a>
+## Use this package
+
+Operations and hunks contain only JSON-serializable values, and parsing retains repeated paths in input order as unresolved strings.
+
+```ts
+import { applyHunks, parsePatch } from '@deepseek-ai/dsh-fs-patch'
+
+const operations = parsePatch('*** Begin Patch\n*** Update File: hello.txt\n-hello\n+hi\n*** End Patch')
+const operation = operations[0]
+if (operation?.kind === 'update') {
+  const result = applyHunks('hello\n', operation.hunks) // { ok: true, after: 'hi\n' }
+}
+```
+
+Malformed input throws `PatchParseError` with a one-based `lineNumber` and a corrective `reason`. Locations count leading blank lines and heredoc wrappers in the original input.
+
+`applyHunks` returns `{ ok: true, after }` or `{ ok: false, failure }` without mutating its inputs. A match failure reports the hunk's patch line, the `context` or `oldLines` stage, the sequential search cursor, and the original unmatched pattern; a trailing-empty-line retry still reports the original pattern. Returning rather than throwing lets callers collect match failures across file operations.
+
+<a id="compatibility"></a>
+## Compatibility
+
+The reference is [OpenAI Codex rust-v0.158.0](https://github.com/openai/codex/tree/rust-v0.158.0/codex-rs/apply-patch/src): `parser.rs` and `streaming_parser.rs` for syntax, and `seek_sequence.rs` and `file_update.rs` for matching and `NormalizeToLf` reconstruction. `text_file.rs` documents the separate line-preserving representation. The [parser tests](tests/parse.spec.ts) and [text tests](tests/apply.spec.ts) adapt selected upstream cases, including `file_update_tests.rs` and `lib.rs`. The [LICENSE](LICENSE) retains OpenAI attribution and Apache-2.0 terms alongside the MIT license for DeepSeek contributions.
+
+### Parsing
+
+| Input | Parsed result |
+|---|---|
+| Begin/End Patch; Add/Delete/Update File headers | Ordered operations; an empty patch and an empty added file are accepted. |
+| Added file lines prefixed by `+` | Prefix removed; each line contributes a final LF. |
+| Update lines prefixed by space, `+`, or `-` | Context, insertion, or deletion; a bare empty line is empty context. |
+| First update without `@@`; later `@@` or `@@ text` | Ordered hunks with an optional context anchor; empty hunks are rejected. |
+| Move to immediately after Update File | Destination on the update; a move without a nonempty hunk is rejected. |
+| End of File after a hunk | EOF flag; following blank lines are ignored and further content requires a new hunk or file header. |
+| LF/CRLF, outer Unicode whitespace, indented headers | Codex trimming rules use Unicode `White_Space`, including U+0085 and excluding BOM (U+FEFF). Indented markers inside updates remain context. Content whitespace is retained. |
+| Literal `<<EOF`, `<<'EOF'`, or `<<"EOF"` wrappers | Accepted without shell evaluation; the closing line must end in `EOF`, as in the reference. |
+| Repeated paths, relative/absolute paths, Unicode text | Retained without path resolution or Unicode normalization. |
+| Environment ID header | Dedicated unsupported-header error before the first operation; ordinary syntax errors elsewhere. |
+| Unified diff, shell commands, malformed markers | Rejected with the original line number; diagnostic wording differs from Codex. |
+
+EOF before any hunk has no effect, matching the reference; an update still requires a nonempty hunk. The reference also accepts a redundant final End Patch after an earlier End Patch and intervening whitespace.
+
+### Matching and text updates
+
+| Input or rule | Result |
+|---|---|
+| Four matching passes | Exact, trailing `White_Space` trimmed on both sides, both ends trimmed, then trimmed Unicode punctuation mapped to ASCII. Each pass searches all candidates before the next pass. |
+| Unicode punctuation | U+2010–2015 and U+2212 map to `-`; U+2018–201B to single quotes; U+201C–201F to double quotes; U+00A0, U+2002–200A, U+202F, U+205F, and U+3000 to space. No NFC/NFKC normalization. |
+| `@@ text` and repeated content | Find the first matching anchor from the cursor, then search after it. Old lines use the first match from that cursor, which advances to the match end. All searches use the original text. |
+| EOF hunk | Search only at `lineCount - patternLength`, even before the cursor. The pinned implementation does not fall back to earlier matches, despite its search-function comment. |
+| Empty old lines | Insert at the original file's end, before its final empty source line when present. The insertion does not advance the cursor; an anchor must still match. Same-position insertions retain patch order. |
+| Unmatched pattern ending in an empty line | Retry without that last line; also remove the last new line if it is empty. An empty retry pattern matches the cursor. |
+| Reconstruction | Remove one terminal empty split element before matching; apply stably sorted replacements in reverse order. Add a terminal empty element unless one exists, then join with LF. Empty output stays empty; nonempty output ends in LF. |
+| Context lines | Replace the complete matched region from patch text, including tolerated context differences. |
+| No hunks | Still perform the same reconstruction, so a missing terminal LF is added and one terminal empty line can be consumed. |
+
+The intentional differences from Codex are ownership and result reporting: the DSH provider preserves line-ending style, so the matcher sees only LF-normalized text and `PreserveLineEndings` is not implemented. CR is an ordinary character: callers must normalize CRLF first and restore the chosen style afterward. Match failures return structured data rather than Codex's path-bearing errors, so the caller owns file identification and user-facing diagnostics.
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+The [parser](src/parse.ts) builds syntax records without a Session or provider dependency. The [text updater](src/apply.ts) locates every hunk against the original text before constructing a complete result. The [types](src/types.ts) carry syntax locations and match failures; the [filesystem reference](../../../docs/subsystems/filesystem.md#patch-syntax-records) owns the public type definitions.
+
+</details>
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+- [Filesystem package group](../README.md) — providers, policies, and file tools.
+- [Apply patch file editing](../../../.agents/notes/implemented/feature/2026-09-28-apply-patch-file-editing.md) — decision record.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- Text updates implement only `NormalizeToLf`; callers own line-ending conversion.
+- The public API accepts complete strings, not streaming deltas.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>

package/README.zh.md

@@ -0,0 +1,112 @@
+---
+description: "解析 Codex 风格补丁并将 hunk 应用于文本，不执行文件系统 I/O。"
+kind: "package-library"
+---
+
+# dsh-fs-patch
+
+[English](README.md) | 中文
+
+## 概述
+
+使用 `parsePatch` 将完整的 Codex 风格补丁解析为有序文件操作，再用 `applyHunks` 将更新 hunk 应用于 LF 规范化文本。两个函数只处理调用方传入的字符串，不访问文件系统。语法错误抛出并标明原始输入行号；匹配返回新文本或结构化失败。
+
+## 目录
+
+- [使用此包](#use-this-package)
+- [兼容性](#compatibility)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [已知限制与后续工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+<a id="use-this-package"></a>
+## 使用此包
+
+操作和 hunk（修改块）只包含可 JSON 序列化的值；解析按输入顺序保留重复路径，路径保持为未解析的字符串。
+
+```ts
+import { applyHunks, parsePatch } from '@deepseek-ai/dsh-fs-patch'
+
+const operations = parsePatch('*** Begin Patch\n*** Update File: hello.txt\n-hello\n+hi\n*** End Patch')
+const operation = operations[0]
+if (operation?.kind === 'update') {
+  const result = applyHunks('hello\n', operation.hunks) // { ok: true, after: 'hi\n' }
+}
+```
+
+非法输入抛出 `PatchParseError`，包含从 1 开始的 `lineNumber` 和说明如何修正的 `reason`。位置计入原始输入中的前导空行和 heredoc 包装。
+
+`applyHunks` 返回 `{ ok: true, after }` 或 `{ ok: false, failure }`，不修改输入。匹配失败报告 hunk 在补丁中的行号、`context` 或 `oldLines` 阶段、顺序搜索游标和原始未匹配模式；移除末尾空行重试后仍报告原始模式。以返回值而非异常报告失败，便于调用方收集多个文件操作的匹配失败。
+
+<a id="compatibility"></a>
+## 兼容性
+
+参照实现为 [OpenAI Codex rust-v0.158.0](https://github.com/openai/codex/tree/rust-v0.158.0/codex-rs/apply-patch/src)：语法参照 `parser.rs` 和 `streaming_parser.rs`，匹配及 `NormalizeToLf` 重建参照 `seek_sequence.rs` 和 `file_update.rs`。`text_file.rs` 说明独立的换行保留表示。[解析器测试](tests/parse.spec.ts) 与[文本测试](tests/apply.spec.ts) 改编选定的上游用例，包括 `file_update_tests.rs` 和 `lib.rs`。[LICENSE](LICENSE) 在 DeepSeek 贡献的 MIT 许可证之外，保留 OpenAI 署名与 Apache-2.0 条款。
+
+### 解析
+
+| 输入 | 解析结果 |
+|---|---|
+| Begin/End Patch；Add/Delete/Update File 头 | 有序操作；接受空补丁和空新增文件。 |
+| 新增文件中以 `+` 为前缀的行 | 去除前缀；每行都附带末尾 LF。 |
+| 更新中以空格、`+` 或 `-` 为前缀的行 | 上下文、插入或删除；没有前缀的空行视为空上下文。 |
+| 首个更新省略 `@@`；后续使用 `@@` 或 `@@ text` | 带可选上下文锚点的有序 hunk；拒绝空 hunk。 |
+| 紧跟 Update File 的 Move to | 更新操作携带目标路径；没有非空 hunk 的移动被拒绝。 |
+| hunk 后的 End of File | 设置 EOF 标志；忽略后续空白行，更多内容需要新的 hunk 或文件头。 |
+| LF/CRLF、外围 Unicode 空白、缩进的文件头 | Codex 裁剪规则使用 Unicode `White_Space`，包含 U+0085，不包含 BOM（U+FEFF）。更新内部缩进的标记仍作为上下文。保留内容空白。 |
+| 字面量 `<<EOF`、`<<'EOF'` 或 `<<"EOF"` 包装 | 接受但不执行 shell；与参照实现相同，结束行必须以 `EOF` 结尾。 |
+| 重复路径、相对/绝对路径、Unicode 文本 | 原样保留，不解析路径或进行 Unicode 归一化。 |
+| Environment ID 头 | 首个操作前给出专用的不支持错误；其他位置给出普通语法错误。 |
+| Unified diff、shell 命令、非法标记 | 拒绝并给出原始行号；诊断措辞与 Codex 不同。 |
+
+与参照实现相同，任何 hunk 之前的 EOF 没有效果；更新仍然需要非空 hunk。参照实现也接受在较早的 End Patch 和中间空白之后重复出现的最终 End Patch。
+
+### 匹配与文本更新
+
+| 输入或规则 | 结果 |
+|---|---|
+| 四级匹配 | 精确匹配、两侧去尾部 `White_Space`、两侧去首尾空白，再将去首尾空白后的 Unicode 标点映射为 ASCII。每一级遍历所有候选后才进入下一级。 |
+| Unicode 标点 | U+2010–2015 和 U+2212 映射为 `-`；U+2018–201B 映射为单引号；U+201C–201F 映射为双引号；U+00A0、U+2002–200A、U+202F、U+205F、U+3000 映射为空格。不做 NFC/NFKC 归一化。 |
+| `@@ text` 与重复内容 | 从游标起找第一个匹配锚点，再从其后一行搜索。旧行取游标后的首个匹配，随后游标推进到匹配末尾。所有搜索都基于原文本。 |
+| EOF hunk | 只从 `lineCount - patternLength` 搜索，即使该位置在游标之前。固定版本的实现不会回退到更早的匹配位置，尽管搜索函数的注释如此描述。 |
+| 旧行为空 | 在原文件末尾插入；若末尾有空源行，则插在该行之前。插入不推进游标；存在锚点时仍须匹配。同位置插入保留补丁顺序。 |
+| 未匹配且末行为空的模式 | 去掉最后一行重试；新行末尾若为空也去掉。重试模式为空时匹配游标位置。 |
+| 文本重建 | 匹配前去掉按 LF 分割所得的一个末尾空元素；按起点稳定排序后反序应用替换。如果末尾没有空元素则补一个，再用 LF 连接。空结果保持空；非空结果以 LF 结尾。 |
+| 上下文行 | 用补丁文本替换整个匹配区间，包括容错匹配的上下文差异。 |
+| 没有 hunk | 仍执行相同的重建，因此会补齐缺少的末尾 LF，也可能消耗一个末尾空行。 |
+
+与 Codex 的刻意差异在于职责和结果报告：行尾风格由 DSH 提供方保留，因此匹配器只接收 LF 规范化文本，不实现 `PreserveLineEndings`。CR 是普通字符：调用方必须先规范化 CRLF，之后还原选定的行尾风格。匹配失败返回结构化数据而非 Codex 带路径的错误，因此调用方负责文件标识和面向用户的诊断。
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现内部机制——点击展开</summary>
+
+[解析器](src/parse.ts) 构建语法记录，不依赖 Session 或提供方。[文本更新器](src/apply.ts) 先在原文本中定位每个 hunk，再构建完整结果。[类型](src/types.ts) 携带语法位置与匹配失败；[文件系统参考](../../../docs/subsystems/filesystem.zh.md#patch-syntax-records) 维护公开类型定义。
+
+</details>
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+- [文件系统包组](../README.zh.md)——提供方、策略和文件工具。
+- [Apply patch 文件编辑](../../../.agents/notes/implemented/feature/2026-09-28-apply-patch-file-editing.zh.md)——决策记录。
+
+## 已知限制与后续工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- 文本更新只实现 `NormalizeToLf`；调用方负责行尾转换。
+- 公开 API 接受完整字符串，不接收流式增量。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者工作上下文——点击展开</summary>
+
+无。
+
+</details>

package/lib/index.js

@@ -0,0 +1,275 @@
+//#region lib/types/parse.js
+/**
+* Batch parser following OpenAI Codex rust-v0.158.0 parser.rs and streaming_parser.rs.
+* Adapted into a pure TypeScript parser with original-input diagnostics and no environment routing.
+* Copyright 2025 OpenAI. Apache-2.0 portions and modification notice: ../LICENSE.
+*/
+const BEGIN = "*** Begin Patch";
+const END = "*** End Patch";
+const EOF = "*** End of File";
+const MOVE = "*** Move to: ";
+const ADD = "*** Add File: ";
+const DELETE = "*** Delete File: ";
+const UPDATE = "*** Update File: ";
+/** Rust uses Unicode White_Space (all in the BMP); JavaScript trim also removes BOM. */
+const WHITE_SPACE$1 = /\p{White_Space}/u;
+/** Syntax failure with a one-based line in the original input, including any wrapper. */
+var PatchParseError = class extends Error {
+	lineNumber;
+	reason;
+	constructor(lineNumber, reason) {
+		super(`Invalid patch at line ${lineNumber}: ${reason}`);
+		this.lineNumber = lineNumber;
+		this.reason = reason;
+		this.name = "PatchParseError";
+	}
+};
+/** Scan the ends to avoid regex backtracking over long interior whitespace. */
+function trim(value) {
+	let start = 0;
+	while (start < value.length && WHITE_SPACE$1.test(value.charAt(start))) start++;
+	return trimEnd(value.slice(start));
+}
+function trimEnd(value) {
+	let end = value.length;
+	while (end > 0 && WHITE_SPACE$1.test(value.charAt(end - 1))) end--;
+	return value.slice(0, end);
+}
+function patchLines(patch) {
+	const offset = patch.slice(0, patch.length - patch.replace(/^\p{White_Space}+/u, "").length).split("\n").length - 1;
+	let lines = trim(patch).split(/\r?\n/u).map((text, index) => ({
+		text,
+		number: offset + index + 1
+	}));
+	const first = lines[0];
+	const last = lines.at(-1);
+	if ([
+		"<<EOF",
+		"<<'EOF'",
+		"<<\"EOF\""
+	].includes(first.text) && last.text.endsWith("EOF") && lines.length >= 4) lines = lines.slice(1, -1);
+	const start = lines[0];
+	const end = lines.at(-1);
+	if (trim(start.text) !== BEGIN) throw new PatchParseError(start.number, `Expected '${BEGIN}'`);
+	if (trim(end.text) !== END) throw new PatchParseError(end.number, `Expected '${END}'`);
+	return lines.map((line, index) => index < lines.length - 1 ? {
+		...line,
+		text: line.text.replace(/\r$/u, "")
+	} : line);
+}
+function emptyHunk(hunk) {
+	return hunk.oldLines.length === 0 && hunk.newLines.length === 0;
+}
+function ensureUpdate(operation, lineNumber) {
+	if (operation?.kind !== "update") return;
+	const last = operation.hunks.at(-1);
+	if (last === void 0) throw new PatchParseError(operation.lineNumber, `Update for '${operation.path}' requires at least one hunk`);
+	if (emptyHunk(last)) throw new PatchParseError(lineNumber, "Update hunk must contain context, added, or removed lines");
+}
+function newHunk(lineNumber) {
+	return {
+		lineNumber,
+		oldLines: [],
+		newLines: [],
+		isEndOfFile: false
+	};
+}
+function readUpdate(operation, line) {
+	const text = trimEnd(line.text);
+	const previous = operation.hunks.at(-1);
+	const marker = text === "@@" || text.startsWith("@@ ");
+	if (previous?.isEndOfFile) {
+		if (text === "") return;
+		if (!marker) throw new PatchParseError(line.number, "Expected '@@' after '*** End of File'");
+	}
+	if (previous === void 0 && operation.moveTo === void 0 && text.startsWith(MOVE)) {
+		operation.moveTo = text.slice(13);
+		return;
+	}
+	if (marker) {
+		if (previous !== void 0 && emptyHunk(previous)) throw new PatchParseError(line.number, "Update hunk must contain context, added, or removed lines");
+		const hunk = newHunk(line.number);
+		if (text.startsWith("@@ ")) hunk.context = text.slice(3);
+		operation.hunks.push(hunk);
+		return;
+	}
+	if (text === EOF) {
+		if (previous !== void 0) {
+			if (emptyHunk(previous)) throw new PatchParseError(line.number, "Update hunk must contain context, added, or removed lines");
+			previous.isEndOfFile = true;
+		}
+		return;
+	}
+	const prefix = line.text[0];
+	if (line.text !== "" && prefix !== " " && prefix !== "+" && prefix !== "-") throw new PatchParseError(line.number, "Expected a context (' '), added ('+'), removed ('-') line, or '@@'");
+	const hunk = previous ?? newHunk(line.number);
+	if (previous === void 0) operation.hunks.push(hunk);
+	const content = line.text.slice(1);
+	if (prefix === "+") hunk.newLines.push(content);
+	else if (prefix === "-") hunk.oldLines.push(content);
+	else {
+		hunk.oldLines.push(content);
+		hunk.newLines.push(content);
+	}
+}
+/**
+* Parse a complete Codex-style patch without reading or modifying files.
+* @param patch - patch text, optionally wrapped in a literal EOF heredoc.
+* @returns ordered, JSON-serializable operations; an empty patch returns an empty array.
+* @throws PatchParseError for malformed syntax or an unsupported Environment ID header.
+*/
+function parsePatch(patch) {
+	const lines = patchLines(patch);
+	const operations = [];
+	let ended = false;
+	for (const line of lines.slice(1)) {
+		const operation = operations.at(-1);
+		const header = operation?.kind === "update" && line !== lines.at(-1) ? trimEnd(line.text) : trim(line.text);
+		if (ended && line !== lines.at(-1)) {
+			if (trim(line.text) !== "") throw new PatchParseError(line.number, `Unexpected content after '${END}'`);
+			continue;
+		}
+		if (header === END) {
+			ensureUpdate(operation, line.number);
+			ended = true;
+		} else if (header.startsWith(ADD)) {
+			ensureUpdate(operation, line.number);
+			operations.push({
+				kind: "add",
+				path: header.slice(14),
+				lineNumber: line.number,
+				content: ""
+			});
+		} else if (header.startsWith(DELETE)) {
+			ensureUpdate(operation, line.number);
+			operations.push({
+				kind: "delete",
+				path: header.slice(17),
+				lineNumber: line.number
+			});
+		} else if (header.startsWith(UPDATE)) {
+			ensureUpdate(operation, line.number);
+			operations.push({
+				kind: "update",
+				path: header.slice(17),
+				lineNumber: line.number,
+				hunks: []
+			});
+		} else if (operations.length === 0 && header.startsWith("*** Environment ID:")) throw new PatchParseError(line.number, "Environment ID headers are unsupported; the caller selects the filesystem provider");
+		else if (operation?.kind === "add" && line.text.startsWith("+")) operation.content += `${line.text.slice(1)}\n`;
+		else if (operation?.kind === "update") readUpdate(operation, line);
+		else throw new PatchParseError(line.number, "Expected an Add File, Delete File, or Update File header; added content must start with +");
+	}
+	return operations;
+}
+//#endregion
+//#region lib/types/apply.js
+/**
+* Pure text updates following OpenAI Codex rust-v0.158.0 NormalizeToLf behavior.
+* Adapted from seek_sequence.rs and file_update.rs with structured match failures.
+* Copyright 2025 OpenAI. Apache-2.0 portions and modification notice: ../LICENSE.
+*/
+const WHITE_SPACE = /\p{White_Space}/u;
+function trimWhitespace(value, leading) {
+	let start = 0;
+	let end = value.length;
+	if (leading) while (start < end && WHITE_SPACE.test(value.charAt(start))) start++;
+	while (end > start && WHITE_SPACE.test(value.charAt(end - 1))) end--;
+	return value.slice(start, end);
+}
+function normalizePunctuation(value) {
+	return trimWhitespace(value, true).replace(/[\u2010-\u2015\u2212]/gu, "-").replace(/[\u2018-\u201B]/gu, "'").replace(/[\u201C-\u201F]/gu, "\"").replace(/[\u00A0\u2002-\u200A\u202F\u205F\u3000]/gu, " ");
+}
+const MATCH_PASSES = [
+	(value) => value,
+	(value) => trimWhitespace(value, false),
+	(value) => trimWhitespace(value, true),
+	normalizePunctuation
+];
+/** NormalizeToLf checks only the tail candidate for EOF, even before the cursor. */
+function seekSequence(lines, pattern, start, eof) {
+	if (pattern.length === 0) return start;
+	if (pattern.length > lines.length) return void 0;
+	const last = lines.length - pattern.length;
+	const first = eof ? last : start;
+	for (const normalize of MATCH_PASSES) {
+		const expected = pattern.map(normalize);
+		for (let index = first; index <= last; index++) if (expected.every((line, offset) => normalize(lines[index + offset]) === line)) return index;
+	}
+}
+/**
+* Apply parsed hunks to LF-normalized text without I/O or input mutation.
+* All searches use the original text; a failed search returns no partial text.
+* Successful nonempty output ends in LF, including initially unterminated text.
+* @param before - text normalized by the caller; CR characters receive no line-ending handling.
+* @param hunks - ordered hunks from parsePatch; EOF searches follow NormalizeToLf tail semantics.
+* @returns new text or the first unmatched hunk, without throwing for a match failure.
+*/
+function applyHunks(before, hunks) {
+	const original = before.split("\n");
+	if (original.at(-1) === "") original.pop();
+	const replacements = [];
+	let lineIndex = 0;
+	for (const hunk of hunks) {
+		if (hunk.context !== void 0) {
+			const pattern = [hunk.context];
+			const found = seekSequence(original, pattern, lineIndex, false);
+			if (found === void 0) return {
+				ok: false,
+				failure: {
+					hunkLineNumber: hunk.lineNumber,
+					stage: "context",
+					searchStart: lineIndex,
+					pattern
+				}
+			};
+			lineIndex = found + 1;
+		}
+		if (hunk.oldLines.length === 0) {
+			const start = original.at(-1) === "" ? original.length - 1 : original.length;
+			replacements.push({
+				start,
+				oldLength: 0,
+				newLines: hunk.newLines
+			});
+			continue;
+		}
+		let pattern = hunk.oldLines;
+		let newLines = hunk.newLines;
+		let found = seekSequence(original, pattern, lineIndex, hunk.isEndOfFile);
+		if (found === void 0 && pattern.at(-1) === "") {
+			pattern = pattern.slice(0, -1);
+			if (newLines.at(-1) === "") newLines = newLines.slice(0, -1);
+			found = seekSequence(original, pattern, lineIndex, hunk.isEndOfFile);
+		}
+		if (found === void 0) return {
+			ok: false,
+			failure: {
+				hunkLineNumber: hunk.lineNumber,
+				stage: "oldLines",
+				searchStart: lineIndex,
+				pattern: [...hunk.oldLines]
+			}
+		};
+		replacements.push({
+			start: found,
+			oldLength: pattern.length,
+			newLines
+		});
+		lineIndex = found + pattern.length;
+	}
+	replacements.sort((left, right) => left.start - right.start);
+	let lines = original;
+	for (const replacement of replacements.reverse()) lines = [
+		...lines.slice(0, replacement.start),
+		...replacement.newLines,
+		...lines.slice(replacement.start + replacement.oldLength)
+	];
+	if (lines.at(-1) !== "") lines.push("");
+	return {
+		ok: true,
+		after: lines.join("\n")
+	};
+}
+//#endregion
+export { PatchParseError, applyHunks, parsePatch };

package/lib/types/apply.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Pure text updates following OpenAI Codex rust-v0.158.0 NormalizeToLf behavior.
+ * Adapted from seek_sequence.rs and file_update.rs with structured match failures.
+ * Copyright 2025 OpenAI. Apache-2.0 portions and modification notice: ../LICENSE.
+ */
+import type { ApplyHunksResult, PatchHunk } from './types.ts';
+/**
+ * Apply parsed hunks to LF-normalized text without I/O or input mutation.
+ * All searches use the original text; a failed search returns no partial text.
+ * Successful nonempty output ends in LF, including initially unterminated text.
+ * @param before - text normalized by the caller; CR characters receive no line-ending handling.
+ * @param hunks - ordered hunks from parsePatch; EOF searches follow NormalizeToLf tail semantics.
+ * @returns new text or the first unmatched hunk, without throwing for a match failure.
+ */
+export declare function applyHunks(before: string, hunks: readonly PatchHunk[]): ApplyHunksResult;
+//# sourceMappingURL=apply.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,5 @@
+/** Pure patch parsing and text application, independent of filesystem providers. */
+export { parsePatch, PatchParseError } from './parse.ts';
+export { applyHunks } from './apply.ts';
+export type { ApplyHunksResult, HunkApplyFailure, PatchHunk, PatchOperation } from './types.ts';
+//# sourceMappingURL=index.d.ts.map

package/lib/types/parse.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Batch parser following OpenAI Codex rust-v0.158.0 parser.rs and streaming_parser.rs.
+ * Adapted into a pure TypeScript parser with original-input diagnostics and no environment routing.
+ * Copyright 2025 OpenAI. Apache-2.0 portions and modification notice: ../LICENSE.
+ */
+import type { PatchOperation } from './types.ts';
+/** Syntax failure with a one-based line in the original input, including any wrapper. */
+export declare class PatchParseError extends Error {
+    readonly lineNumber: number;
+    readonly reason: string;
+    constructor(lineNumber: number, reason: string);
+}
+/**
+ * Parse a complete Codex-style patch without reading or modifying files.
+ * @param patch - patch text, optionally wrapped in a literal EOF heredoc.
+ * @returns ordered, JSON-serializable operations; an empty patch returns an empty array.
+ * @throws PatchParseError for malformed syntax or an unsupported Environment ID header.
+ */
+export declare function parsePatch(patch: string): PatchOperation[];
+//# sourceMappingURL=parse.d.ts.map

package/lib/types/types.d.ts

@@ -0,0 +1,52 @@
+/** Serializable patch syntax and text-application results; paths remain unresolved. */
+/** One contiguous update. */
+export interface PatchHunk {
+    /** One-based input line containing the marker or first implicit hunk line. */
+    lineNumber: number;
+    /** Text following `@@ `, used as a search anchor by the text matcher. */
+    context?: string;
+    /** Context and removed lines, without patch prefixes or line endings. */
+    oldLines: string[];
+    /** Context and added lines, without patch prefixes or line endings. */
+    newLines: string[];
+    /** Whether `*** End of File` follows this hunk. */
+    isEndOfFile: boolean;
+}
+/** Ordered file operation; a move is an update with a destination path. */
+export type PatchOperation = {
+    kind: 'add';
+    path: string;
+    lineNumber: number;
+    /** Added lines joined with LF, including a final LF for every added line. */
+    content: string;
+} | {
+    kind: 'delete';
+    path: string;
+    lineNumber: number;
+} | {
+    kind: 'update';
+    path: string;
+    lineNumber: number;
+    moveTo?: string;
+    hunks: PatchHunk[];
+};
+/** The first hunk whose anchor or old lines could not be located in the original text. */
+export interface HunkApplyFailure {
+    /** One-based line of the failing hunk in the patch input. */
+    hunkLineNumber: number;
+    /** The failed anchor or old-content search. */
+    stage: 'context' | 'oldLines';
+    /** Zero-based sequential search cursor; EOF searches override it with the tail candidate. */
+    searchStart: number;
+    /** Original anchor or old lines, including any trailing empty line retried without its sentinel. */
+    pattern: string[];
+}
+/** Complete new text or a match failure; failures contain no partially updated text. */
+export type ApplyHunksResult = {
+    ok: true;
+    after: string;
+} | {
+    ok: false;
+    failure: HunkApplyFailure;
+};
+//# sourceMappingURL=types.d.ts.map

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@deepseek-ai/dsh-fs-patch",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Pure Codex-style patch parser and LF text updater with structured match failures",
+  "version": "0.2.2-alpha.3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/fs/fs-patch"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "~4.0.6-alpha.2"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "~4.0.6-alpha.2"
+  }
 }