@mafianacho/nacholens 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 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/NOTICE

@@ -0,0 +1,13 @@
+nacholens
+Copyright 2026 Mafianacho
+
+This product includes no third-party code, icons or images.
+
+It includes fonts licensed under the SIL Open Font License, Version 1.1 (not under Apache-2.0), in
+src/player/fonts/, embedded into every generated page:
+  - Nacho Sans, Nacho Mono: Modified Versions (subset, WOFF2, renamed) of IBM Plex Sans and IBM Plex Mono,
+    Copyright 2017 IBM Corp. with Reserved Font Name "Plex". See src/player/fonts/OFL-IBMPlex.txt.
+  - Anton (subset, WOFF2): Copyright 2020 The Anton Project Authors. See src/player/fonts/OFL-Anton.txt.
+Details and source checksums: src/player/fonts/FONTLOG.md. The look follows the Nacho Combo design system
+(https://github.com/mafianacho/nachocombo). The player needs no network access.
+(The Apache-2.0 license text in LICENSE is the unmodified text from apache.org.)

package/README.de.md

@@ -0,0 +1,46 @@
+# nacholens
+
+[English](README.md) · [日本語](README.ja.md) · **Deutsch** · [Français](README.fr.md) · [中文](README.zh.md) · [한국어](README.ko.md)
+
+Sieh, was eine KI in einem Backend geändert hat, ohne Code zu lesen. nacholens macht aus einem Repository eine einzige Seite: Wähle einen Anwendungsfall und sieh, wie die Anfrage vom Client durch deine Dienste, die Datenbank und Drittanbieter läuft. Die geänderten Teile sind aus `git diff` hervorgehoben.
+
+![nacholens: eine Anfrage läuft durch den Demo-Shop, geänderte Teile hervorgehoben](docs/images/overview.png)
+
+## Verwendung
+
+Öffne deinen KI-Coding-Agenten (Claude Code, Codex, Cursor, …) im Repository, das du sehen willst. Kopiere den Block unten, schreibe deine Anfrage in die Zeile `Meine Anfrage:` und füge ihn ein.
+
+```text
+Nutze nacholens, um meine Anfrage unten zu diesem Repository als Seite zu beantworten, die ich öffnen kann.
+
+Meine Anfrage: <hier schreiben, was du sehen willst>
+
+So geht's:
+1. Hole das nacholens-Playbook und die CLI (braucht Node.js 20+ und git; in dieses Repository wird nichts installiert):
+   npx -y @mafianacho/nacholens@latest install --to "$HOME/.nacholens-skill" --force
+2. Lies "$HOME/.nacholens-skill/nacholens/SKILL.md" und folge ihm. Die CLI ist:
+   node "$HOME/.nacholens-skill/nacholens/cli/src/cli.js" <command>
+3. Ändere keine Datei dieses Repositorys außer dem Modell in .nacholens/. Schreibe die Seite nach ./nacholens-out.
+4. Wenn die Seite fertig ist, nenne mir ihren Pfad und erkläre in einfachen Worten, was sie zeigt.
+```
+
+Beispielanfragen:
+
+- `Was hat sich in den letzten 5 Commits geändert, und was sollte ich erneut testen?`
+- `Zeig, wie die Anmeldung funktioniert, vom Browser bis zur Datenbank.`
+- `Vergleiche diesen Branch mit main: Welche Abläufe hat diese Arbeit berührt?`
+
+## Demo ausprobieren
+
+```bash
+npx -y @mafianacho/nacholens@latest demo
+# → ./nacholens-demo/demo-shop.html (im Browser öffnen)
+```
+
+## Mehr
+
+- [Anleitung](docs/guide.md) (Englisch): Befehle, wie die Änderungsansicht funktioniert, Grenzen
+- [Agenten-Playbook](skills/nacholens/SKILL.md), [Modellformat](docs/model-schema.md), [Review-Dock](docs/review.md)
+- [Mitwirken](CONTRIBUTING.md), [Sicherheit](SECURITY.md)
+
+Apache License 2.0 ([`LICENSE`](LICENSE), [`NOTICE`](NOTICE)). Die eingebetteten Schriften stehen unter der SIL Open Font License 1.1 ([`FONTLOG`](src/player/fonts/FONTLOG.md)). Made by [Mafianacho Inc.](https://mafianacho.com)

package/README.fr.md

@@ -0,0 +1,46 @@
+# nacholens
+
+[English](README.md) · [日本語](README.ja.md) · [Deutsch](README.de.md) · **Français** · [中文](README.zh.md) · [한국어](README.ko.md)
+
+Voyez ce qu'une IA a changé dans un backend, sans lire le code. nacholens transforme un dépôt en une seule page : choisissez un cas d'usage et regardez la requête passer du client à vos services, à la base de données et aux services tiers, les parties modifiées étant mises en évidence à partir de `git diff`.
+
+![nacholens : une requête traverse la boutique de démonstration, parties modifiées en évidence](docs/images/overview.png)
+
+## Utilisation
+
+Ouvrez votre agent de code IA (Claude Code, Codex, Cursor, …) dans le dépôt que vous voulez voir, copiez le bloc ci-dessous, écrivez votre demande sur la ligne `Ma demande :` et collez-le.
+
+```text
+Utilise nacholens pour répondre à ma demande ci-dessous sur ce dépôt, sous la forme d'une page que je peux ouvrir.
+
+Ma demande : <écrivez ici ce que vous voulez voir>
+
+Comment :
+1. Récupère le guide d'agent et la CLI de nacholens (Node.js 20+ et git nécessaires ; rien n'est installé dans ce dépôt) :
+   npx -y @mafianacho/nacholens@latest install --to "$HOME/.nacholens-skill" --force
+2. Lis "$HOME/.nacholens-skill/nacholens/SKILL.md" et suis-le. La CLI est :
+   node "$HOME/.nacholens-skill/nacholens/cli/src/cli.js" <command>
+3. Ne modifie aucun fichier de ce dépôt, sauf le modèle dans .nacholens/. Écris la page dans ./nacholens-out.
+4. Une fois la page générée, donne-moi son chemin et explique simplement ce qu'elle montre.
+```
+
+Exemples de demandes:
+
+- `Qu'est-ce qui a changé dans les 5 derniers commits, et que dois-je retester ?`
+- `Montre comment fonctionne la connexion, du navigateur à la base de données.`
+- `Compare cette branche avec main : quels parcours ce travail a-t-il touchés ?`
+
+## Essayer la démo
+
+```bash
+npx -y @mafianacho/nacholens@latest demo
+# → ./nacholens-demo/demo-shop.html (à ouvrir dans un navigateur)
+```
+
+## Plus
+
+- [Guide](docs/guide.md) (en anglais) : commandes, fonctionnement de la vue des changements, limites
+- [Guide d'agent](skills/nacholens/SKILL.md), [format du modèle](docs/model-schema.md), [panneau de revue](docs/review.md)
+- [Contribuer](CONTRIBUTING.md), [Sécurité](SECURITY.md)
+
+Apache License 2.0 ([`LICENSE`](LICENSE), [`NOTICE`](NOTICE)). Les polices intégrées sont sous SIL Open Font License 1.1 ([`FONTLOG`](src/player/fonts/FONTLOG.md)). Made by [Mafianacho Inc.](https://mafianacho.com)

package/README.ja.md

@@ -0,0 +1,46 @@
+# nacholens
+
+[English](README.md) · **日本語** · [Deutsch](README.de.md) · [Français](README.fr.md) · [中文](README.zh.md) · [한국어](README.ko.md)
+
+AIがバックエンドに加えた変更を、コードを読まずに確かめられます。nacholens はリポジトリを1枚のページにします。ユースケースを選ぶと、リクエストがクライアントからサービス、データベース、外部サービスへと動き、`git diff` から求めた変更箇所が強調されます。
+
+![nacholens: デモショップを流れるリクエストと強調された変更箇所](docs/images/overview.png)
+
+## 使い方
+
+見たいリポジトリで AI コーディングエージェント（Claude Code、Codex、Cursor など）を開き、下のブロックをコピーして `依頼:` の行に見たいことを書き、そのまま貼り付けてください。
+
+```text
+nacholens を使って、このリポジトリについての下の依頼に、開けるページで答えてください。
+
+依頼: <見たいことをここに書く>
+
+手順:
+1. nacholens の手順書と CLI を取得する（Node.js 20 以上と git が必要。このリポジトリには何もインストールしない）:
+   npx -y @mafianacho/nacholens@latest install --to "$HOME/.nacholens-skill" --force
+2. "$HOME/.nacholens-skill/nacholens/SKILL.md" を読み、その手順に従う。CLI は次のとおり:
+   node "$HOME/.nacholens-skill/nacholens/cli/src/cli.js" <command>
+3. .nacholens/ のモデル以外、このリポジトリのファイルは変更しない。ページは ./nacholens-out に書き出す。
+4. ページができたら、そのパスを伝え、何が分かるかを平易な言葉で説明する。
+```
+
+依頼の例:
+
+- `直近5コミットで何が変わった？何を再テストすべき？`
+- `ログインの流れを、ブラウザからデータベースまで見せて。`
+- `このブランチを main と比べて、この作業が触れたフローはどれ？`
+
+## デモを試す
+
+```bash
+npx -y @mafianacho/nacholens@latest demo
+# → ./nacholens-demo/demo-shop.html（ブラウザで開く）
+```
+
+## 詳しく
+
+- [ガイド](docs/guide.md)（英語）: コマンド、変更オーバーレイの仕組み、制限
+- [エージェント用手順書](skills/nacholens/SKILL.md)、[モデル形式](docs/model-schema.md)、[レビュードック](docs/review.md)
+- [コントリビュート](CONTRIBUTING.md)、[セキュリティ](SECURITY.md)
+
+Apache License 2.0（[`LICENSE`](LICENSE)、[`NOTICE`](NOTICE)）。同梱フォントは SIL Open Font License 1.1 です（[`FONTLOG`](src/player/fonts/FONTLOG.md)）。Made by [Mafianacho Inc.](https://mafianacho.com)

package/README.ko.md

@@ -0,0 +1,46 @@
+# nacholens
+
+[English](README.md) · [日本語](README.ja.md) · [Deutsch](README.de.md) · [Français](README.fr.md) · [中文](README.zh.md) · **한국어**
+
+AI가 백엔드에서 무엇을 바꿨는지 코드를 읽지 않고 확인하세요. nacholens는 저장소를 한 페이지로 보여 줍니다. 유즈케이스를 고르면 요청이 클라이언트에서 서비스, 데이터베이스, 외부 서비스로 움직이고, `git diff`로 찾은 바뀐 곳이 강조됩니다.
+
+![nacholens: 데모 쇼핑몰을 지나가는 요청과 강조된 변경 부분](docs/images/overview.png)
+
+## 사용법
+
+보고 싶은 저장소에서 AI 코딩 에이전트(Claude Code, Codex, Cursor 등)를 열고, 아래 블록을 복사해 `요청:` 줄에 보고 싶은 것을 적은 뒤 그대로 붙여 넣으세요.
+
+```text
+nacholens로 이 저장소에 대한 아래 요청에, 열어 볼 수 있는 페이지로 답해 줘.
+
+요청: <보고 싶은 것을 여기에 적기>
+
+방법:
+1. nacholens 플레이북과 CLI를 받는다 (Node.js 20 이상과 git 필요, 이 저장소에는 아무것도 설치하지 않음):
+   npx -y @mafianacho/nacholens@latest install --to "$HOME/.nacholens-skill" --force
+2. "$HOME/.nacholens-skill/nacholens/SKILL.md" 를 읽고 그대로 따른다. CLI는 다음과 같다:
+   node "$HOME/.nacholens-skill/nacholens/cli/src/cli.js" <command>
+3. .nacholens/ 의 모델 말고는 이 저장소의 파일을 바꾸지 않는다. 페이지는 ./nacholens-out 에 만든다.
+4. 페이지가 만들어지면 경로를 알려 주고, 무엇을 보여 주는지 쉬운 말로 설명한다.
+```
+
+요청 예시:
+
+- `최근 커밋 5개에서 뭐가 바뀌었고, 무엇을 다시 테스트해야 해?`
+- `로그인이 브라우저에서 데이터베이스까지 어떻게 흐르는지 보여 줘.`
+- `이 브랜치를 main과 비교해서 이번 작업이 건드린 흐름을 알려 줘.`
+
+## 데모 보기
+
+```bash
+npx -y @mafianacho/nacholens@latest demo
+# → ./nacholens-demo/demo-shop.html (브라우저로 열기)
+```
+
+## 더 보기
+
+- [안내서](docs/guide.ko.md): 명령, 변경 강조가 만들어지는 방식, 한계
+- [에이전트 플레이북](skills/nacholens/SKILL.md), [모델 형식](docs/model-schema.md), [검토 독](docs/review.md)
+- [기여하기](CONTRIBUTING.md), [보안](SECURITY.md)
+
+Apache License 2.0 ([`LICENSE`](LICENSE), [`NOTICE`](NOTICE)). 내장 글꼴은 SIL Open Font License 1.1을 따릅니다 ([`FONTLOG`](src/player/fonts/FONTLOG.md)). Made by [Mafianacho Inc.](https://mafianacho.com)

package/README.md

@@ -1,3 +1,46 @@
-# Temporary Holding Version
+# nacholens
 
-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.
+**English** · [日本語](README.ja.md) · [Deutsch](README.de.md) · [Français](README.fr.md) · [中文](README.zh.md) · [한국어](README.ko.md)
+
+See what an AI changed in a backend, without reading code. nacholens turns a repository into one page: pick a use case and watch the request move from the client through your services, database and third parties, with the changed parts highlighted from `git diff`.
+
+![nacholens: a request moving through the demo shop, changed parts highlighted](docs/images/overview.png)
+
+## Use it
+
+Open your AI coding agent (Claude Code, Codex, Cursor, …) in the repository you want to see, copy the block below, write your request on the `My request:` line, and paste it.
+
+```text
+Use nacholens to answer my request below about this repository, as a page I can open.
+
+My request: <write what you want to see here>
+
+How:
+1. Get the nacholens playbook and CLI (needs Node.js 20+ and git; nothing is installed into this repository):
+   npx -y @mafianacho/nacholens@latest install --to "$HOME/.nacholens-skill" --force
+2. Read "$HOME/.nacholens-skill/nacholens/SKILL.md" and follow it. The CLI is:
+   node "$HOME/.nacholens-skill/nacholens/cli/src/cli.js" <command>
+3. Do not change any file of this repository except the model in .nacholens/. Write the page to ./nacholens-out.
+4. When the page is built, give me its path and explain what it shows in plain words.
+```
+
+Example requests:
+
+- `What changed in the last 5 commits, and what should I re-test?`
+- `Show how sign-in works, from the browser to the database.`
+- `Compare this branch with main: which flows did this work touch?`
+
+## Try the demo
+
+```bash
+npx -y @mafianacho/nacholens@latest demo
+# → ./nacholens-demo/demo-shop.html (open it in a browser)
+```
+
+## More
+
+- [Guide](docs/guide.md): commands, how the change overlay works, limits
+- [Agent playbook](skills/nacholens/SKILL.md), [model format](docs/model-schema.md), [review dock](docs/review.md)
+- [Contributing](CONTRIBUTING.md), [Security](SECURITY.md)
+
+Apache License 2.0 ([`LICENSE`](LICENSE), [`NOTICE`](NOTICE)). The embedded fonts are under the SIL Open Font License 1.1 ([`FONTLOG`](src/player/fonts/FONTLOG.md)). Made by [Mafianacho Inc.](https://mafianacho.com)

package/README.zh.md

@@ -0,0 +1,46 @@
+# nacholens
+
+[English](README.md) · [日本語](README.ja.md) · [Deutsch](README.de.md) · [Français](README.fr.md) · **中文** · [한국어](README.ko.md)
+
+不读代码，也能看清 AI 改了后端的哪些地方。nacholens 把一个代码仓库变成一个页面：选一个用例，就能看到请求从客户端经过你的服务、数据库和第三方服务，并根据 `git diff` 高亮显示改动的部分。
+
+![nacholens：请求在演示商店中流动，改动部分被高亮](docs/images/overview.png)
+
+## 用法
+
+在要查看的仓库里打开你的 AI 编程助手（Claude Code、Codex、Cursor 等），复制下面的代码块，在 `我的请求：` 一行写下你想看的内容，然后直接粘贴。
+
+```text
+请用 nacholens 回答我下面关于这个仓库的请求，结果做成一个我能打开的页面。
+
+我的请求：<在这里写你想看的内容>
+
+做法：
+1. 获取 nacholens 的操作手册和 CLI（需要 Node.js 20+ 和 git；不会往这个仓库安装任何东西）：
+   npx -y @mafianacho/nacholens@latest install --to "$HOME/.nacholens-skill" --force
+2. 阅读 "$HOME/.nacholens-skill/nacholens/SKILL.md" 并照做。CLI 是：
+   node "$HOME/.nacholens-skill/nacholens/cli/src/cli.js" <command>
+3. 除 .nacholens/ 里的模型外，不要修改这个仓库的任何文件。页面写到 ./nacholens-out。
+4. 页面生成后，告诉我它的路径，并用通俗的话说明它展示了什么。
+```
+
+请求示例:
+
+- `最近 5 次提交改了什么？我需要重新测试哪些？`
+- `展示登录是怎么工作的，从浏览器到数据库。`
+- `把这个分支和 main 比较：这次工作涉及了哪些流程？`
+
+## 试试演示
+
+```bash
+npx -y @mafianacho/nacholens@latest demo
+# → ./nacholens-demo/demo-shop.html（用浏览器打开）
+```
+
+## 更多
+
+- [指南](docs/guide.md)（英文）：命令、改动叠加的原理、局限
+- [助手操作手册](skills/nacholens/SKILL.md)、[模型格式](docs/model-schema.md)、[评审面板](docs/review.md)
+- [参与贡献](CONTRIBUTING.md)、[安全](SECURITY.md)
+
+Apache License 2.0（[`LICENSE`](LICENSE)、[`NOTICE`](NOTICE)）。内嵌字体采用 SIL Open Font License 1.1（[`FONTLOG`](src/player/fonts/FONTLOG.md)）。Made by [Mafianacho Inc.](https://mafianacho.com)

package/demo/shop/v1/README.md

@@ -0,0 +1,7 @@
+# demo shop (v1)
+
+Tiny zero-dependency Node app used as the public example for `nacholens`:
+browser (`public/`) → gateway (`gateway.js`) → API (`api.js`) → SQLite (`db.js`),
+plus three third-party services (`mock-external.js`).
+
+    node mock-external.js & node api.js & node gateway.js    # Node >= 22.13

package/demo/shop/v1/api.js

@@ -0,0 +1,78 @@
+// Order API: sessions, orders, sales report. Talks to SQLite and to external services.
+import http from "node:http";
+import { randomUUID } from "node:crypto";
+import { saveState, consumeState, saveSession, findSession, listOrders, insertOrder } from "./db.js";
+
+const EXTERNAL = process.env.EXTERNAL_URL ?? "http://127.0.0.1:8090";
+const PUBLIC_ORIGIN = process.env.PUBLIC_ORIGIN ?? "http://127.0.0.1:8080";
+const SESSION_TTL_MS = 8 * 60 * 60 * 1000;
+const ADMINS = new Set((process.env.ADMIN_EMAILS ?? "buyer@example.com").split(","));
+
+const send = (res, code, body, headers = {}) => {
+  res.writeHead(code, { "content-type": "application/json", ...headers });
+  res.end(JSON.stringify(body));
+};
+
+const readBody = (req) => new Promise((resolve) => {
+  let raw = "";
+  req.on("data", (c) => (raw += c));
+  req.on("end", () => { try { resolve(JSON.parse(raw || "{}")); } catch { resolve(null); } });
+});
+
+function sessionOf(req) {
+  const m = /(?:^|; )sid=([\w-]+)/.exec(req.headers.cookie ?? "");
+  return m ? findSession(m[1]) : null;
+}
+
+async function route(req, res) {
+  const url = new URL(req.url, "http://x");
+  const key = `${req.method} ${url.pathname}`;
+
+  if (key === "GET /api/auth/start") {
+    const state = randomUUID();
+    saveState(state);
+    const to = new URL(EXTERNAL + "/authorize");
+    to.searchParams.set("state", state);
+    to.searchParams.set("redirect_uri", PUBLIC_ORIGIN + "/api/auth/callback");
+    return send(res, 302, { redirect: to.toString() }, { location: to.toString() });
+  }
+
+  if (key === "GET /api/auth/callback") {
+    if (!consumeState(url.searchParams.get("state") ?? "")) return send(res, 400, { error: "bad_state" });
+    const token = await fetch(EXTERNAL + "/token", { method: "POST", body: JSON.stringify({ code: url.searchParams.get("code") }) });
+    if (!token.ok) return send(res, 502, { error: "provider_failed" });
+    const { email } = await token.json();
+    const sid = randomUUID();
+    saveSession(sid, email, SESSION_TTL_MS);
+    return send(res, 302, { ok: true }, { location: "/", "set-cookie": `sid=${sid}; HttpOnly; SameSite=Lax; Path=/; Max-Age=${SESSION_TTL_MS / 1000}` });
+  }
+
+  const me = sessionOf(req);
+  if (!me) return send(res, 401, { error: "unauthenticated" });
+
+  if (key === "GET /api/orders") {
+    const rows = listOrders(me.email);
+    return send(res, 200, { orders: rows.map((o) => ({ id: o.id, item: o.item, qty: o.qty, createdAt: o.created_at })) });
+  }
+
+  if (key === "POST /api/orders") {
+    if (req.headers.origin !== PUBLIC_ORIGIN) return send(res, 403, { error: "bad_origin" });
+    const body = await readBody(req);
+    if (!body || typeof body.item !== "string" || !Number.isInteger(body.qty) || body.qty < 1 || body.qty > 99)
+      return send(res, 400, { error: "invalid_order" });
+    const id = insertOrder(me.email, body.item.slice(0, 80), body.qty);
+    return send(res, 201, { id });
+  }
+
+  if (key === "GET /api/reports/sales") {
+    if (!ADMINS.has(me.email)) return send(res, 403, { error: "forbidden" });
+    const r = await fetch(EXTERNAL + "/sales");
+    if (!r.ok) return send(res, 502, { error: "analytics_unavailable" });
+    return send(res, 200, await r.json());
+  }
+
+  send(res, 404, { error: "not_found" });
+}
+
+const server = http.createServer((req, res) => route(req, res).catch(() => send(res, 500, { error: "internal" })));
+server.listen(Number(process.env.API_PORT ?? 8081), "127.0.0.1", () => console.log("listening on :" + server.address().port));

package/demo/shop/v1/db.js

@@ -0,0 +1,38 @@
+// SQLite storage for the demo shop (node:sqlite, Node >= 22.13).
+import { DatabaseSync } from "node:sqlite";
+
+const db = new DatabaseSync(process.env.SHOP_DB ?? ":memory:");
+db.exec(`
+  CREATE TABLE IF NOT EXISTS oauth_state (state TEXT PRIMARY KEY, created_at INTEGER NOT NULL);
+  CREATE TABLE IF NOT EXISTS sessions (id TEXT PRIMARY KEY, email TEXT NOT NULL, expires_at INTEGER NOT NULL);
+  CREATE TABLE IF NOT EXISTS orders (
+    id INTEGER PRIMARY KEY AUTOINCREMENT, email TEXT NOT NULL, item TEXT NOT NULL,
+    qty INTEGER NOT NULL, tracking TEXT, created_at INTEGER NOT NULL
+  );
+`);
+
+export function saveState(state) {
+  db.prepare("INSERT INTO oauth_state (state, created_at) VALUES (?, ?)").run(state, Date.now());
+}
+
+// A state value works once: the row is removed in the same statement that reads it.
+export function consumeState(state) {
+  return db.prepare("DELETE FROM oauth_state WHERE state = ? RETURNING state").get(state) ?? null;
+}
+
+export function saveSession(id, email, ttlMs) {
+  db.prepare("INSERT INTO sessions (id, email, expires_at) VALUES (?, ?, ?)").run(id, email, Date.now() + ttlMs);
+}
+
+export function findSession(id) {
+  return db.prepare("SELECT email FROM sessions WHERE id = ? AND expires_at > ?").get(id, Date.now()) ?? null;
+}
+
+export function listOrders(email) {
+  return db.prepare("SELECT id, item, qty, tracking, created_at FROM orders WHERE email = ? ORDER BY id DESC LIMIT 50").all(email);
+}
+
+export function insertOrder(email, item, qty, tracking) {
+  const r = db.prepare("INSERT INTO orders (email, item, qty, tracking, created_at) VALUES (?, ?, ?, ?, ?)").run(email, item, qty, tracking ?? null, Date.now());
+  return Number(r.lastInsertRowid);
+}