prompt-contract 0.2.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/README.md

@@ -0,0 +1,102 @@
+# ✨ PromptContract
+
+[![CI](https://github.com/QianJinGuo/prompt-contract/actions/workflows/ci.yml/badge.svg)](https://github.com/QianJinGuo/prompt-contract/actions/workflows/ci.yml)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
+![Node](https://img.shields.io/badge/node-%E2%89%A520-brightgreen)
+[![GitHub release](https://img.shields.io/github/v/tag/QianJinGuo/prompt-contract?sort=semver)](https://github.com/QianJinGuo/prompt-contract/releases)
+
+English · [简体中文](README.zh-CN.md)
+
+![PromptContract playground running the self-contained demo: a vague one-line request enhanced into a structured task spec, with six rule assertions passing](docs/assets/hero-playground.png)
+<sub>The playground running its self-contained demo (`?demo=1`) against the local mock upstream — actual pipeline output, six rule assertions passing.</sub>
+
+**PromptContract is a deterministic prompt-contract layer for AI coding agents.** It compiles a vague one-line request into a structured task specification — goal, scope, constraints, acceptance criteria — and verifies the result against six hard rules before you ever see it.
+
+It is *not* a smarter brain: your model does the thinking, PromptContract makes the input stable, reviewable, and portable across models and tools.
+
+## Why PromptContract
+
+- **Stable agent inputs** — a profile plus hard constraints turn "a website for my dog" into goal / scope / acceptance criteria / explicit non-goals. Reduced retries and scope drift are hypotheses measured by the task-level harness, not current product claims.
+- **Six deterministic guardrails** — language consistency, enhanced-text-only, length & completeness, expand-don't-answer, no hallucinated tech. Every enhancement can be asserted with `contract check`; the same spec drives templates and tests.
+- **One engine, three surfaces** — a CLI, an MCP server (agent-invoked **tool** + user-invoked **slash prompts**), and a browser playground. All share one zero-dependency core.
+- **Private by architecture** — bring your own key, no server in the middle, no telemetry, offline-capable via Ollama.
+
+## Quick start — 30 seconds, no API key
+
+```bash
+git clone https://github.com/QianJinGuo/prompt-contract && cd prompt-contract
+node mock/server.js &                                   # local mock upstream
+node packages/cli/bin/contract.js "帮我做一个展示我家狗的网站" \
+  --provider openai --base-url http://127.0.0.1:8787/v1 --api-key test-key-123 --model mock-model
+node packages/playground/serve.js                       # → http://127.0.0.1:8123/  (or ?demo=1 for the self-running demo)
+```
+
+Install: `npm i -g prompt-contract` — or zero-install: `npx prompt-contract "your vague idea"`.
+
+## Your real model
+
+```bash
+export CONTRACT_API_KEY=sk-xxx CONTRACT_MODEL=gpt-4o-mini    # any OpenAI-compatible endpoint (DeepSeek, Qwen, GLM, vLLM…)
+contract "A website for my dog"
+
+export CONTRACT_PROVIDER=ollama CONTRACT_MODEL=qwen3:4b      # fully local/offline; keep_alive pins the model in RAM
+contract "帮我写一封请假邮件"
+```
+
+Or write `~/.prompt-contract/config.json` once: `{ "provider": "openai", "baseUrl": "…", "apiKey": "…", "model": "…" }`.
+
+## MCP integration
+
+```json
+{ "mcpServers": { "prompt-contract": { "command": "node", "args": ["/abs/path/packages/mcp-server/bin/prompt-contract-mcp.js"] } } }
+```
+
+| Mode | Invocation | Needs a key? |
+|---|---|---|
+| **Tool** `enhance_prompt(text, profile?, strength?, context?)` | the agent calls it before executing a vague task | yes (your configured provider) |
+| **Prompts** `/contract-coding-agent`, `/contract-writing`, `/contract-image-gen` | you invoke; the rewrite spec is injected into the **client's own model** | **no — zero config, server starts unconfigured** |
+
+## Choose a profile
+
+| Profile | Turns vague input into | Output cap |
+|---|---|---|
+| `coding-agent` | goal, scope, acceptance criteria, non-goals for a coding agent | 800 chars |
+| `writing` | audience, tone, structure, preservation constraints | 800 chars |
+| `image-gen` | subject, composition, lighting, style | 600 chars |
+
+Community profiles are the main contribution surface — a PR adding `profiles/<name>.md` plus eval cases is a complete contribution (see [CONTRIBUTING.md](CONTRIBUTING.md)).
+
+## Quality gates — and their honest limits
+
+```bash
+npm test        # 60 tests: engine units + SSE/ndjson streaming + CLI/MCP e2e against a local mock
+npm run eval    # 9 deterministic cases over the six hard-constraint assertions
+npm run eval:tasks -- --format-only  # validate the coding-agent task fixture format gate
+npm run bench   # engine overhead: P50 ≈ 0.005ms (budget < 5ms)
+```
+
+**What this does and does not prove:** these gates prove the *pipeline* is correct (streaming, cancellation, error codes, MCP handshake) and that outputs pass format constraints. The paired task-level harness is documented in [docs/TASK-EVAL.md](docs/TASK-EVAL.md), but no downstream task results are included yet. It therefore makes no claim that enhanced prompts improve completion, retries, scope drift, hallucinations, token cost, or latency.
+
+## How it works
+
+```
+raw input → script/scenario detect → profile + hard constraints + strength (+ optional context)
+  → single streaming LLM call (small fast model by default; the model does the thinking)
+  → deterministic cleaning (quotes/fences/length clamp, empty → llm_error)
+  → { enhanced, original, meta } — original always preserved, one-key revert in every surface
+```
+
+## Status & roadmap — stated honestly
+
+- **Shipped:** engine, CLI (`contract` / `check` / `doctor` / `profiles` / `spike-0`), MCP server (tool + zero-key prompts), playground, 3 profiles, eval cases, CI matrix.
+- **Gated:** `contract watch` (global-hotkey resident mode) remains intentionally unavailable. `contract spike-0` measures macOS capture/clipboard safety and dry-run focus eligibility, but never pastes or unlocks watch by itself; see [docs/SPIKE-0.md](docs/SPIKE-0.md).
+- **Open validation:** task-level outcome evaluation remains an evidence-gathering task. The harness and curated fixture set exist, but PromptContract's downstream effectiveness is still a hypothesis until a declared runner produces reviewed results.
+- Deferred: animated demo asset, IDE plugins, LLM-as-judge as *one* scorer inside the task-level eval.
+
+## Layout
+
+`packages/core` (engine, browser-safe, zero deps) · `packages/providers` (OpenAI-compatible SSE + Ollama `keep_alive`) · `packages/cli` · `packages/mcp-server` · `packages/playground` · `profiles/` · `eval/` · `mock/` · `docs/ACCEPTANCE.md` · `docs/SPIKE-0.md` (requirements → implementation → acceptance + evidence boundaries)
+
+## Contributing & License
+
+[CONTRIBUTING.md](CONTRIBUTING.md) · [Code of Conduct](CODE_OF_CONDUCT.md) · [Security policy](SECURITY.md) · Apache-2.0

package/README.zh-CN.md

@@ -0,0 +1,73 @@
+# ✨ PromptContract
+
+[![CI](https://github.com/QianJinGuo/prompt-contract/actions/workflows/ci.yml/badge.svg)](https://github.com/QianJinGuo/prompt-contract/actions/workflows/ci.yml)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
+![Node](https://img.shields.io/badge/node-%E2%89%A520-brightgreen)
+
+[English](README.md) · 简体中文
+
+**PromptContract 是面向 AI 编码 agent 的确定性 prompt 契约层**：把模糊的一句话编译成结构化任务规范（目标 / 范围 / 约束 / 验收标准），并在你看到结果之前用六条硬规则完成校验。
+
+它不是「更聪明的大脑」：思考由你的模型完成，PromptContract 让 agent 的输入变得稳定、可审查、可跨模型与跨工具迁移。
+
+![Playground 自运行演示：模糊一句话被增强为结构化任务规范，六条规则断言全部通过](docs/assets/hero-playground.png)
+
+## 为什么
+
+- **稳定的 agent 输入**——profile + 硬约束把「帮我做个网站」编译成目标 / 范围 / 验收标准 / 明确不做的事；重试与范围漂移是否减少，仍须由任务级 harness 验证，当前不作产品结论
+- **六条确定性护栏**——语言一致性、只输出增强文本、长度与完整性、扩写而非回答、无幻觉技术栈；`contract check` 随时可断言，模板与测试共用同一份规格
+- **一个引擎、三个形态**——CLI、MCP server（agent 调用的 tool + 用户调用的斜杠 prompts）、浏览器 Playground，共享同一个零依赖内核
+- **隐私即架构**——BYOK、无中间服务、零遥测，Ollama 全本地可用
+
+## 30 秒上手（无需 API key）
+
+```bash
+git clone https://github.com/QianJinGuo/prompt-contract && cd prompt-contract
+node mock/server.js &                                   # 本地 mock 上游
+node packages/cli/bin/contract.js "帮我做一个展示我家狗的网站" \
+  --provider openai --base-url http://127.0.0.1:8787/v1 --api-key test-key-123 --model mock-model
+node packages/playground/serve.js                       # → http://127.0.0.1:8123/（?demo=1 为自运行演示）
+```
+
+安装：`npm i -g prompt-contract`；或零安装体验：`npx prompt-contract "你的模糊想法"`。
+
+## 接入真实模型
+
+```bash
+export CONTRACT_API_KEY=sk-xxx CONTRACT_MODEL=gpt-4o-mini   # 任意 OpenAI 兼容端点（DeepSeek/Qwen/GLM/vLLM…）
+contract "A website for my dog"
+
+export CONTRACT_PROVIDER=ollama CONTRACT_MODEL=qwen3:4b     # 全本地；keep_alive 把模型钉在内存
+contract "帮我写一封请假邮件"
+```
+
+或一次写入 `~/.prompt-contract/config.json`。
+
+## MCP 接入
+
+| 模式 | 调用方 | 需要 key？ |
+|---|---|---|
+| **Tool** `enhance_prompt(text, profile?, strength?, context?)` | agent 在执行模糊任务前自行调用 | 需要（走你配置的 provider） |
+| **Prompts** `/contract-coding-agent` 等 | 你手动调用；改写规范注入**客户端自有模型** | **不需要——服务器可在零配置下启动** |
+
+## 质量门禁与诚实边界
+
+```bash
+npm test        # 60 项：引擎单测 + SSE/ndjson 流式 + CLI/MCP 端到端（对本地 mock）
+npm run eval    # 9 个确定性用例（六条硬约束断言）
+npm run eval:tasks -- --format-only  # 校验 coding-agent 任务 fixture 的格式门禁
+npm run bench   # 引擎自身开销 P50 ≈ 0.005ms（预算 <5ms）
+```
+
+**这些证明的是管线正确与格式合规，不证明「增强后的 prompt 提升了下游任务效果」**。任务级 harness 与 fixture 见 [docs/TASK-EVAL.md](docs/TASK-EVAL.md)，但仓库尚未包含下游任务结果，因此不作有效性结论。
+
+## 状态与路线图（诚实版）
+
+- **已交付**：引擎、CLI（含 `spike-0`）、MCP server（tool + 零 key prompts）、Playground、3 个 profiles、eval 用例、CI 矩阵
+- **被门控**：`contract watch`（全局热键常驻）仍不可用。`contract spike-0` 只测 macOS 取词、剪贴板恢复和焦点校验的 dry-run，不发送粘贴，也不会自行解锁 watch；见 [docs/SPIKE-0.md](docs/SPIKE-0.md)
+- **开放验证**：任务级效果评测的 harness 与任务 fixture 已交付，但还没有声明 runner 产生并复核结果；长期价值在此之前仍是假设
+- **推迟**：动画 demo 资产、IDE 插件、LLM-as-judge（作为任务级评测中的评分器之一）
+
+## 贡献与许可
+
+[CONTRIBUTING.md](CONTRIBUTING.md)（新增 profile = 新增场景，PR 即贡献）· [行为准则](CODE_OF_CONDUCT.md) · [安全策略](SECURITY.md) · Apache-2.0

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "prompt-contract",
+  "version": "0.2.0",
+  "description": "pc — one-key prompt enhancement: turn vague ideas into structured task specs anywhere you type to an AI. CLI + MCP server. Zero dependencies, BYOK, offline-capable (Ollama).",
+  "license": "Apache-2.0",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "contract": "./packages/cli/bin/contract.js",
+    "prompt-contract": "./packages/cli/bin/contract.js",
+    "prompt-contract-mcp": "./packages/mcp-server/bin/prompt-contract-mcp.js",
+    "pb": "./packages/cli/bin/contract.js"
+  },
+  "keywords": [
+    "prompt",
+    "prompt-contract",
+    "prompt-engineering",
+    "llm",
+    "cli",
+    "mcp",
+    "model-context-protocol",
+    "ai-agents",
+    "ollama",
+    "openai",
+    "developer-tools"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/QianJinGuo/prompt-contract.git"
+  },
+  "homepage": "https://github.com/QianJinGuo/prompt-contract#readme",
+  "bugs": "https://github.com/QianJinGuo/prompt-contract/issues",
+  "files": [
+    "packages/",
+    "profiles/",
+    "README.md",
+    "README.en.md",
+    "LICENSE"
+  ]
+}