@kujolang/paperclip 0.1.5 → 0.1.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (12) hide show
  1. package/CHANGELOG.md +22 -0
  2. package/README.md +86 -39
  3. package/VERSION +1 -1
  4. package/dist/manifest.js +6002 -1650
  5. package/dist/worker.js +6570 -2218
  6. package/docs/COMPATIBILITY.md +1 -1
  7. package/docs/INSTALLATION.md +6 -0
  8. package/docs/MAINTENANCE_HANDOFF.md +263 -0
  9. package/docs/README.md +1 -0
  10. package/docs/RELEASE_READINESS.md +4 -3
  11. package/docs/USAGE.md +3 -3
  12. package/package.json +14 -10
package/CHANGELOG.md CHANGED
@@ -1,5 +1,27 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.1.7 - 2026-09-04
4
+
5
+ - Rewrite the README in plain English with a 30-second install path, first-use steps,
6
+ copyable agent requests, and clear compatibility notes.
7
+ - Add monochrome npm and CI badges alongside the standard Kujo version, license, and
8
+ build badges.
9
+ - Correct the documented Context Pack file limits and reject unknown `npm run`
10
+ commands in repository documentation.
11
+ - Upgrade the bundled Kujo runtime to 1.2.3 and refresh the Node and React DOM type
12
+ definitions after full verification.
13
+
14
+ ## 0.1.6 - 2026-09-03
15
+
16
+ - Add deterministic Chromium coverage for both Paperclip UI surfaces, all primary
17
+ actions, project/issue/run states, accessible branding, responsive themes, and
18
+ approved visual baselines.
19
+ - Gate pull requests and tagged releases on the browser suite, with failure reports
20
+ retained for diagnosis.
21
+ - Upgrade Zod, React development types, Rollup, TypeScript, Vitest, build provenance,
22
+ and dependency-review tooling after passing the full compatibility matrix.
23
+ - Make Node and React compiler types explicit for TypeScript 7.
24
+
3
25
  ## 0.1.5 - 2026-09-02
4
26
 
5
27
  - Replace the temporary lettermark in the Paperclip workspace with the official adaptive Kujo SVG from kujolang.ai.
package/README.md CHANGED
@@ -1,12 +1,16 @@
1
1
  # Kujo for Paperclip
2
2
 
3
- [![Version](https://img.shields.io/badge/version-0.1.5-black)](https://github.com/kujolang/paperclip/releases/tag/v0.1.5)
3
+ [![Version](https://img.shields.io/badge/version-0.1.7-black)](https://github.com/kujolang/paperclip/releases/tag/v0.1.7)
4
+ [![npm](https://img.shields.io/npm/v/%40kujolang%2Fpaperclip?label=npm&color=black)](https://www.npmjs.com/package/@kujolang/paperclip)
5
+ [![CI](https://img.shields.io/github/actions/workflow/status/kujolang/paperclip/ci.yml?branch=main&label=CI&color=black)](https://github.com/kujolang/paperclip/actions/workflows/ci.yml)
4
6
  [![License](https://img.shields.io/badge/license-MIT-lightgrey)](LICENSE)
5
7
  [![built with Kujo](https://img.shields.io/badge/built%20with-Kujo-white.svg)](https://github.com/kujolang/kujo)
6
8
 
7
- Add scoped context, change review, and reproducible failure evidence to Paperclip.
9
+ Kujo helps Paperclip agents choose useful context, review changes, and save clear
10
+ failure evidence. It runs locally inside Paperclip and works in the current task view.
11
+ You do not need the Classic Task Interface.
8
12
 
9
- ## Install
13
+ ## Install in 30 seconds
10
14
 
11
15
  You need Paperclip `2026.824.1` or later and Node.js `24.11.0` or later.
12
16
 
@@ -14,48 +18,69 @@ You need Paperclip `2026.824.1` or later and Node.js `24.11.0` or later.
14
18
  npx paperclipai plugin install @kujolang/paperclip
15
19
  ```
16
20
 
17
- Restart Paperclip if it is already running. Kujo appears automatically inside Paperclip's current task view. On project and run pages, open the **Kujo** tab. You do not need to switch to the Classic Task Interface.
21
+ Restart Paperclip if it is already running, then open an issue. The Kujo workspace
22
+ appears in the task view. You can also open the **Kujo** tab on project, issue detail,
23
+ and run pages.
18
24
 
19
- The npm package includes the correct Kujo runtime for macOS arm64/x64, Linux arm64/x64, and Windows x64. Installation does not run `preinstall`, `install`, or `postinstall` scripts.
25
+ The npm package includes the right Kujo runtime for macOS arm64/x64, Linux arm64/x64,
26
+ and Windows x64. You do not need a separate Kujo install or Kujo API key. Installation
27
+ does not run `preinstall`, `install`, or `postinstall` scripts.
20
28
 
21
- See [Installation](docs/INSTALLATION.md) for upgrades, local development installs, and uninstall behavior.
29
+ Use the package name exactly as shown for now. Current Paperclip releases mishandle a
30
+ scoped package with an exact version suffix. The upstream fix is open in
31
+ [paperclipai/paperclip#12745](https://github.com/paperclipai/paperclip/pull/12745).
22
32
 
23
- ## Use
33
+ See [Installation](docs/INSTALLATION.md) for upgrades, local development installs,
34
+ uninstall behavior, and release checks.
24
35
 
25
- Open an issue to use the inline Kujo workspace, or open the **Kujo** tab on a project, issue detail page, or run to:
36
+ ## First use
26
37
 
27
- - generate a **Review Pack** for the working tree;
28
- - create a task-specific **Context Pack**;
29
- - capture bounded, redacted **Failure Evidence**.
38
+ 1. Open the Paperclip issue you want to work on.
39
+ 2. Generate a focused **Context Pack** before the agent reads the repository broadly.
40
+ 3. Make and test the change with the project's normal tools.
41
+ 4. Generate a **Review Pack** to inspect scope, risk, and suggested checks.
42
+ 5. If a command fails, save its bounded output as **Failure Evidence**.
30
43
 
31
- Agents can call four tools:
44
+ Kujo stores the latest result in Paperclip plugin state. It does not write reports into
45
+ the project repository.
46
+
47
+ ## What Kujo adds
48
+
49
+ | Workflow | What it does | Kujo component |
50
+ | --- | --- | --- |
51
+ | **Context Pack** | Selects a small, task-specific set of files before an agent reads broadly. | Scent |
52
+ | **Review Pack** | Measures change size, explains risk signals, and prepares a review handoff. | ChangeBucket and PatchBrief |
53
+ | **Failure Evidence** | Turns supplied command details and logs into a bounded, redacted record. | CaseFile |
54
+
55
+ The four component snapshots are pinned, checksummed, and shipped with the plugin. The
56
+ plugin does not download component code while installing or running.
57
+
58
+ ## Agent tools
59
+
60
+ Paperclip agents can call four tools:
32
61
 
33
62
  | Tool | Use |
34
63
  | --- | --- |
35
- | `kujolang.paperclip:review-changes` | Measure change size and create a review handoff. |
36
- | `kujolang.paperclip:capture-failure` | Save supplied command output as redacted evidence. It never reruns the command. |
37
- | `kujolang.paperclip:get-context` | Select a bounded set of files for a task. |
38
- | `kujolang.paperclip:get-context-content` | Read safe content from files selected by an existing Context Pack. |
64
+ | `kujolang.paperclip:get-context` | Select files for a task at minimal, focused, or broad depth. |
65
+ | `kujolang.paperclip:get-context-content` | Read safe content from files already selected by a Context Pack. |
66
+ | `kujolang.paperclip:review-changes` | Measure a working tree or Git range and create a review handoff. |
67
+ | `kujolang.paperclip:capture-failure` | Save supplied command output as redacted evidence. It never runs the command. |
39
68
 
40
- Example agent requests:
69
+ Example requests:
41
70
 
42
71
  ```text
43
72
  Use kujolang.paperclip:get-context with task "trace the OAuth callback" and depth "focused".
44
- Use kujolang.paperclip:review-changes after the edit and report the suggested tests as suggestions, not completed checks.
73
+ Read only the selected files needed for the change.
74
+ Use kujolang.paperclip:review-changes after the edit.
75
+ Report suggested tests as suggestions, not completed checks.
45
76
  If a check fails, use kujolang.paperclip:capture-failure with the command, exit code, and bounded log.
46
77
  ```
47
78
 
48
- The content tool only reads files selected by the matching Context Pack. It rejects other paths, binary files, oversized files, traversal, and symlink escapes.
79
+ The content tool reads only files selected by the matching Context Pack. It rejects
80
+ other paths, binary files, oversized files, traversal, and symlink escapes.
49
81
 
50
- See [Usage](docs/USAGE.md) for tool inputs, UI actions, artifact fields, and common workflows.
51
-
52
- ## What it adds
53
-
54
- - **Review Pack** uses ChangeBucket to measure the change and PatchBrief to explain it.
55
- - **Failure Evidence** uses CaseFile to turn supplied logs into a reviewable record.
56
- - **Context Pack** uses Scent to select relevant files before an agent reads broadly.
57
-
58
- All four component snapshots are pinned, checksummed, and shipped in the package. The plugin does not fetch component code at runtime.
82
+ See [Usage](docs/USAGE.md) for all tool inputs, UI actions, artifact fields, and the
83
+ recommended agent sequence.
59
84
 
60
85
  ## Compatibility
61
86
 
@@ -63,38 +88,58 @@ All four component snapshots are pinned, checksummed, and shipped in the package
63
88
  | --- | --- |
64
89
  | Paperclip host | `>=2026.824.1` |
65
90
  | `@paperclipai/plugin-sdk` | `2026.824.1` |
66
- | `@kujolang/kujo-runtime` | `1.2.2` |
91
+ | `@kujolang/kujo-runtime` | `1.2.3` |
67
92
  | Node.js | `>=24.11.0` |
68
93
 
69
- The npm package is `@kujolang/paperclip`. Its Paperclip manifest ID is `kujolang.paperclip` because manifest IDs do not accept npm scope syntax.
94
+ The npm package is `@kujolang/paperclip`. Its Paperclip manifest ID is
95
+ `kujolang.paperclip` because manifest IDs do not accept npm scope syntax.
96
+
97
+ The plugin tests the minimum supported Paperclip SDK and the latest compatible SDK in
98
+ CI. Its manifest temporarily accepts the host's `0.0.0` fallback until Paperclip ships
99
+ the host-version fix in PR #12745; the documented and tested support floor remains
100
+ `2026.824.1`.
70
101
 
71
102
  ## Configure
72
103
 
73
- Paperclip builds the settings form from the plugin manifest. You can enable or disable each feature, set an absolute Kujo binary override, allow or deny `PATH` fallback, and change bounded process limits.
104
+ Paperclip builds the settings form from the plugin manifest. You can turn each feature
105
+ on or off, set an absolute Kujo binary override, allow or deny `PATH` fallback, and
106
+ change bounded process limits.
74
107
 
75
- Defaults are safe for normal repositories: a 27-second timeout, 2 MB stdout limit, and 256 KB stderr limit. The timeout stays below Paperclip's bridge deadline so the worker can return a structured result. See [Configuration](docs/CONFIGURATION.md) for every setting and limit.
108
+ The defaults suit normal repositories: a 27-second timeout, 2 MB stdout limit, and
109
+ 256 KB stderr limit. The timeout stays below Paperclip's bridge deadline so the worker
110
+ can return a structured result. See [Configuration](docs/CONFIGURATION.md) for every
111
+ setting and limit.
76
112
 
77
113
  ## How it runs
78
114
 
79
- The worker resolves Kujo in this order:
115
+ The worker looks for Kujo in this order:
80
116
 
81
- 1. configured absolute binary;
82
- 2. bundled `@kujolang/kujo-runtime` binary;
117
+ 1. a configured absolute binary;
118
+ 2. the bundled `@kujolang/kujo-runtime` binary;
83
119
  3. an absolute `kujo` found on `PATH`, when allowed;
84
120
  4. a structured error with a repair hint.
85
121
 
86
- Each child process uses an argument array with `shell: false`, a small environment, a canonical Paperclip workspace, a timeout, and output caps. Review and context commands are read-only. Failure Evidence records supplied text and never exposes a command runner.
122
+ Each child process receives an argument array with `shell: false`, a small environment,
123
+ a canonical Paperclip workspace, a timeout, and output caps. Review and Context Pack
124
+ commands are read-only. Failure Evidence records supplied text and never exposes a
125
+ command runner.
87
126
 
88
127
  ## Develop
89
128
 
90
129
  ```bash
91
130
  npm ci --ignore-scripts
92
131
  npm run verify
132
+ npx playwright install chromium
133
+ npm run test:ui
93
134
  ```
94
135
 
95
- `npm run verify` type-checks the source, runs contract, hardening, and real-component tests, verifies component checksums, audits dependency integrity and licenses, produces an SBOM, builds the worker/manifest/UI bundles, and inspects the npm tarball.
136
+ `npm run verify` checks repository conventions, types, contracts, hardening,
137
+ real-component behavior, component checksums, dependency integrity, licenses, the
138
+ SBOM, bundles, and the npm tarball. The Playwright suite covers both Paperclip UI
139
+ surfaces, their actions, responsive layouts, accessibility, and approved screenshots.
96
140
 
97
- Read [AGENTS.md](AGENTS.md) before agent-assisted changes and [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request.
141
+ Read [AGENTS.md](AGENTS.md) before agent-assisted changes and
142
+ [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request.
98
143
 
99
144
  ## Documentation
100
145
 
@@ -109,8 +154,10 @@ Read [AGENTS.md](AGENTS.md) before agent-assisted changes and [CONTRIBUTING.md](
109
154
  - [Troubleshooting](docs/TROUBLESHOOTING.md)
110
155
  - [Release readiness](docs/RELEASE_READINESS.md)
111
156
  - [Operations](docs/OPERATIONS.md)
157
+ - [Maintenance handoff](docs/MAINTENANCE_HANDOFF.md)
112
158
  - [Agent workflow example](examples/agent-workflow.md)
113
159
 
114
160
  ## License
115
161
 
116
- MIT. Bundled Kujo components keep their canonical MIT licenses and recorded provenance.
162
+ MIT. Bundled Kujo components keep their canonical MIT licenses and recorded
163
+ provenance.
package/VERSION CHANGED
@@ -1 +1 @@
1
- 0.1.5
1
+ 0.1.7