cherry-works 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tam Nguyen
+
+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.

package/README.md

@@ -0,0 +1,253 @@
+# Cherry Works
+
+A charter engine for coding agents. You write your team's standards as small
+markdown files, and `cw` checks them, tests them and compiles them into the
+files your coding agent actually reads.
+
+```text
+.cw/charter/guide/no-any.md   ──cw build──▶   CLAUDE.md
+.cw/charter/sensor/lint.md                    .claude/rules/…
+.cw/charter/posture/secrets.md                .claude/settings.json (hooks, permissions)
+…                                             .claude/skills/…, .claude/commands/…
+```
+
+## Why
+
+A coding agent follows whatever instructions it can see. Those instructions
+usually end up as one long prompt file that nobody reviews and that falls out of
+date. Cherry Works handles them the way you handle code:
+
+- **Small, typed files.** Each rule is a separate primitive of one kind, such as
+  a guide, a sensor or a posture. Each kind says which fields it requires and
+  when it comes up.
+- **One build.** `cw build` regenerates every file the agent reads from the
+  charter in one pass. Nothing is edited by hand, and a rule you delete
+  disappears from the output.
+- **Checked and tested.** `cw doctor` names each broken file and says how to fix
+  it. `cw test` runs cases that pin down which rule must come up for which file
+  or event. It runs no command and needs no agent, so the result is the same on
+  every machine.
+- **Shared without copying.** You can install another team's charter as a vendor
+  source. It is pinned to a version and committed with your code, and it never
+  silently overrides your own rules.
+
+## Requirements
+
+- Node.js 22 or later
+- git
+- A supported agent. Today that is [Claude Code](https://claude.com/claude-code).
+  `cw` always writes a neutral output under `.cw/out/` as well.
+
+## Install
+
+```bash
+npm install -g cherry-works
+cw --help
+```
+
+To run it once without installing anything, use `npx cherry-works <command>`.
+To pin one version to a repository, so that its scripts and its CI run that
+version whatever is installed globally, add it as a development dependency:
+
+```bash
+npm install -D cherry-works
+npx cw --version
+```
+
+`cw --version` prints the version you are running. Upgrade with
+`npm install -g cherry-works@latest`.
+
+## Install from source
+
+To run `cw` from a checkout of this repository, you also need pnpm 10 or later.
+Build it and link it globally:
+
+```bash
+git clone https://github.com/tamnguyenvt/cherry-works.git
+cd cherry-works
+pnpm install
+pnpm build
+pnpm link --global
+cw --help
+```
+
+The link points at your checkout. After you change the sources, run
+`pnpm build` again. To remove the link, run `pnpm uninstall --global cherry-works`.
+
+## Quick start
+
+Inside the git repository you want to govern:
+
+```bash
+cw init                       # asks which agent to compile for, then scaffolds .cw/charter/
+cw kinds guide                # what a guide requires
+cw add guide no-any --header description="No any in TypeScript." --header globs="src/**/*.ts"
+cw edit guide:no-any          # write the body in $VISUAL or $EDITOR
+cw build                      # compile the charter for your agent
+cw doctor                     # check that everything holds
+```
+
+Commit `.cw/` together with what `cw build` wrote. Your agent now reads the rule
+in every session in this repository.
+
+## The charter
+
+A primitive is a markdown file with YAML front matter. The folder it sits in
+names its kind:
+
+```markdown
+---
+kind: guide
+id: no-single-word-naming
+description: How to name a function or a variable.
+globs: ["src/**/*.ts"]
+---
+
+Never name a function or variable with a single vague word such as `it`, `data`
+or `merged`. Name it after what it holds or does.
+```
+
+Each kind comes up at a different time:
+
+| Kind | Comes up when |
+|---|---|
+| `guide` | a touched file matches one of its `globs`, or on every turn when it has no globs |
+| `sensor` | the `signal` it names is raised, and the harness runs its `run` command |
+| `command` | it is asked for by name, or a request matches its description |
+| `skill` | one of its `triggers` matches the request |
+| `playbook` | one of its `triggers` matches; its body is a sequence of commands |
+| `agent` | it is spawned by identity, with only the `tools` it lists |
+| `posture` | always, wherever the host can be told what to `allow` and `deny` |
+| `corpus` | a primitive's `rationale` cites it, to give the reasoning behind a rule |
+| `mixin` | never on its own; its body is lent to the primitives that pull it in |
+
+`cw kinds <kind>` gives the exact fields each kind takes. An identity is
+`kind:id`, and it names exactly one primitive across the whole charter. If two
+files claim the same identity, the build is refused and both files are named.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `cw init [--agent]` | Set the repository up under a charter |
+| `cw build [--preview]` | Compile the charter, or show what a build would write |
+| `cw list [--kind] [--min]` | List what the charter holds |
+| `cw kinds [kind]` | List the kinds, or the fields one of them requires |
+| `cw add <kind> <id> [--header k=v …]` | Write a new primitive |
+| `cw edit <identity>` | Open a primitive's file in your editor |
+| `cw remove <identity> [--yes]` | Delete a primitive this repository authored |
+| `cw explain <identity>` | Show which file declares an identity, what it pulls in and which tests name it |
+| `cw doctor` | Check the agents, the charter, the vendor sources and the compiled output |
+| `cw test` | Run every case in `.cw/test/` against the charter |
+| `cw suite add \| edit \| remove` | Manage test files |
+| `cw vendor add <source> [--ref] \| remove \| list` | Install, update, remove or list vendor sources |
+| `cw portal [--port]` | Open the charter in a browser on this machine |
+
+`cw doctor` exits with a failure status when the charter has an error, when a
+vendored file was edited in this repository, or when the compiled output no
+longer matches the charter. That makes it a gate you can run in CI.
+
+## The portal
+
+If you would rather not remember commands and field names, run the portal from
+inside a governed repository:
+
+```bash
+cw portal               # serves on port 9927, or the next free port
+cw portal --port 8080
+```
+
+It prints an address such as `http://127.0.0.1:9927/?t=…`. Open that address in
+your browser. The page has three tabs:
+
+![The Repo Charter tab: kind chips, and the guides of a repository with their globs, rationale and mixins](docs/images/portal-charter.png)
+
+- **Repo Charter** lists every primitive of this repository by kind, with the
+  engine's own line on when that kind comes up. From here you can create a
+  primitive, then open it to edit its fields and its markdown body, or delete
+  it. The form is built from what the kind requires, so it asks only for the
+  fields that kind takes. The **?** on a row explains the primitive: when it
+  comes up, what it pulls in, what cites it and which tests name it.
+
+  | Editing a primitive | Explaining it |
+  |---|---|
+  | ![The form for guide:no-any, with its globs, rationale, mixins and markdown body](docs/images/portal-edit.png) | ![The explanation of guide:no-any: when it comes up, what it pulls in and the test that names it](docs/images/portal-explain.png) |
+- **Vendor** lists the vendor sources you installed and their primitives, which
+  are read-only. You can add a source by its git address and a version, or
+  remove one.
+- **Test** lists the test files in `.cw/test/`. You can create, edit and delete
+  them, and run every case to see which pass and why a failing one failed.
+
+  ![The Test tab after a run: 4 of 5 cases pass, and the failing case says why](docs/images/portal-tests.png)
+
+The header has a search that finds any primitive in any layer, and two buttons:
+**Build**, which shows what a build would write before it writes anything, and
+**Doctor**, which runs the health check and offers a build when the output is
+behind.
+
+The portal drives the same engine as the command line and adds no behaviour of
+its own. What it shows is what the engine answered, and everything it does has
+a command-line equivalent. When the engine refuses a change, the portal shows
+the refusal in the engine's words and writes nothing. It listens only on
+`127.0.0.1`, and every request needs the token in the printed address. Stop it
+with Ctrl+C.
+
+## Testing a charter
+
+A test file in `.cw/test/` describes situations and what must come up in each
+one:
+
+```json
+{
+  "description": "The TypeScript guide comes up on source files.",
+  "cases": [
+    { "do": { "touchFile": "src/one.ts" }, "expect": { "activate": "guide:no-any" } },
+    { "when": "Stop", "expect": { "run": "sensor:lint" } },
+    { "do": { "touchFile": ".env" }, "expect": { "allow": false } }
+  ]
+}
+```
+
+`cw test` resolves each case against the charter and reports the ones that no
+longer hold.
+
+## Vendor sources
+
+```bash
+cw vendor add git@github.com:your-org/charter-baseline.git --ref v1.2.0
+```
+
+A vendor source is a git repository with primitives laid out in folders by kind.
+It is installed under `.cw/vendor/<name>/`, pinned to the ref you chose and
+committed. Vendored primitives are read-only. To differ from one, write your own
+primitive under a new identity.
+
+## Your agent can write rules too
+
+Every governed repository gets a built-in skill, `skill:cw-author`. It teaches
+the agent to ask `cw kinds` what a kind requires and to write primitives with
+`cw add`, instead of copying fields from memory.
+
+## Development
+
+```bash
+pnpm install
+pnpm exec playwright install chromium   # once per machine, for the portal's browser tests
+pnpm test                               # dependency rules, build, then every test
+pnpm typecheck
+pnpm cw <command>                       # run the CLI from source, without building
+```
+
+A release is `pnpm release <version>`, run from a clean `develop` level with
+`origin/develop`. It runs the tests, installs the exact package it would publish
+into a fresh repository and builds it there, and only then commits, tags
+`v<version>`, publishes and pushes. `pnpm release <version> --dry-run` runs
+every check and changes nothing. A plain `npm publish` is refused.
+
+The engine follows a hexagonal layout. `src/hexagon/` holds the domain, the
+application use cases and their ports. `src/driver/` holds the CLI and the
+portal that drive it. `src/zdriven/` holds the adapters for files, git and YAML.
+The design is written in [specs/spec.md](specs/spec.md) and
+[specs/plan.md](specs/plan.md).
+
+This repository is governed by its own charter under [.cw/charter/](.cw/charter/).

package/dist/cw.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+
+// package.json
+var package_default = {
+  name: "cherry-works",
+  version: "0.1.0",
+  description: "The charter engine: resolves a charter and compiles it into what a coding agent reads.",
+  keywords: [
+    "claude-code",
+    "coding-agent",
+    "charter",
+    "ai-agents",
+    "cli",
+    "guardrails"
+  ],
+  homepage: "https://github.com/tamnguyenvt/cherry-works#readme",
+  bugs: {
+    url: "https://github.com/tamnguyenvt/cherry-works/issues"
+  },
+  repository: {
+    type: "git",
+    url: "git+https://github.com/tamnguyenvt/cherry-works.git"
+  },
+  license: "MIT",
+  author: "Tam Nguyen",
+  type: "module",
+  engines: {
+    node: ">=22",
+    pnpm: ">=10"
+  },
+  packageManager: "pnpm@10.2.1",
+  bin: {
+    cw: "./dist/cw.js"
+  },
+  files: [
+    "dist"
+  ],
+  imports: {
+    "#hexagon/*": "./src/hexagon/*",
+    "#portal/*": "./dist/portal/*"
+  },
+  scripts: {
+    build: "tsup && tailwindcss -i src/driver/portal/page/styles.css -o dist/portal/styles.css --minify",
+    typecheck: "tsc --noEmit && tsc --noEmit -p src/driver/portal/page",
+    test: 'pnpm run lint:deps && pnpm run build && node --import tsx --test "test/**/*.test.ts"',
+    cw: "node --import tsx main.ts",
+    "lint:deps": "depcruise src main.ts",
+    "specs:link": "node --import tsx scripts/link-specs.ts",
+    "specs:check": "node --import tsx scripts/link-specs.ts --check",
+    release: "node --import tsx scripts/release.ts",
+    prepublishOnly: `node -e "console.error('Publish with \\"pnpm release <version>\\", which checks the package first.'); process.exit(1)"`
+  },
+  devDependencies: {
+    "@codemirror/commands": "^6.11.1",
+    "@codemirror/lang-markdown": "^6.5.2",
+    "@codemirror/language": "^6.12.4",
+    "@codemirror/state": "^6.7.4",
+    "@codemirror/view": "^6.43.11",
+    "@tailwindcss/cli": "^4.3.3",
+    "@tanstack/react-query": "^5.103.2",
+    "@types/node": "^22.10.2",
+    "@types/picomatch": "^4.0.3",
+    "@types/prompts": "^2.4.9",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@types/yargs": "^17.0.35",
+    "class-variance-authority": "^0.7.1",
+    clsx: "^2.1.1",
+    cmdk: "^1.1.1",
+    "dependency-cruiser": "^18.2.0",
+    "lucide-react": "^1.47.0",
+    marked: "^18.0.13",
+    playwright: "^1.63.0",
+    "radix-ui": "^1.6.7",
+    react: "^19.3.0",
+    "react-dom": "^19.3.0",
+    sonner: "^2.0.8",
+    "tailwind-merge": "^3.7.0",
+    tailwindcss: "^4.3.3",
+    tsup: "^8.3.5",
+    tsx: "^4.19.2",
+    "tw-animate-css": "^1.4.0",
+    typescript: "^5.7.2"
+  },
+  pnpm: {
+    onlyBuiltDependencies: [
+      "esbuild"
+    ]
+  },
+  dependencies: {
+    "@hono/node-server": "^2.1.1",
+    "@hono/zod-openapi": "^1.6.3",
+    hono: "^4.13.7",
+    picomatch: "^4.0.7",
+    prompts: "^2.4.2",
+    yaml: "^2.9.0",
+    yargs: "^18.1.0",
+    zod: "^4.6.1"
+  }
+};
+
+// bin.ts
+var _a;
+var neededMajor = Number((_a = /\d+/.exec(package_default.engines.node)) == null ? void 0 : _a[0]);
+var runningMajor = Number(process.versions.node.split(".")[0]);
+if (runningMajor < neededMajor) {
+  process.stderr.write(
+    `cw needs Node.js ${neededMajor} or later, and this is Node.js ${process.versions.node}.
+Install Node.js ${neededMajor} or later, then run cw again.
+`
+  );
+  process.exitCode = 1;
+} else {
+  const commandEntry = "./main.js";
+  void import(commandEntry);
+}