@kujolang/paperclip 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 0.1.0 - 2026-09-02
+
+- Add Review Pack, Failure Evidence, and Context Pack tools and UI actions for Paperclip.
+- Bundle and verify ChangeBucket, PatchBrief, CaseFile, and Scent component snapshots.
+- Enforce company-scoped state, feature policy, stale-context rejection, workspace bounds, hostile Git configuration suppression, and process-tree cleanup.
+- Add cross-platform compatibility, dependency review, CodeQL, SBOM, provenance, signed-tag, and exact-tarball release controls.
+
+## 0.1.0
+
+- Initial Paperclip-native Review Pack, Failure Evidence, and Context Pack.
+- Lifecycle-script-free Kujo runtime resolution and deterministic component bundle.
+- Strict workspace, process, output, redaction, schema, provenance, and stale-state boundaries.
+- Monochrome project badges and install-first ecosystem documentation.
+- Root agent, contribution, security, and version contracts.
+- Reproducible lockfile-based CI and npm release gates.
+- Exact Kujo `1.2.2` runtime dependency with the restored Windows package build.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kujolang
+
+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,116 @@
+# Kujo for Paperclip
+
+[![Version](https://img.shields.io/badge/version-0.1.0-black)](https://github.com/kujolang/paperclip/releases/tag/v0.1.0)
+[![License](https://img.shields.io/badge/license-MIT-lightgrey)](LICENSE)
+[![built with Kujo](https://img.shields.io/badge/built%20with-Kujo-white.svg)](https://github.com/kujolang/kujo)
+
+Add scoped context, change review, and reproducible failure evidence to Paperclip.
+
+## Install
+
+You need Paperclip `2026.824.1` or later and Node.js `24.11.0` or later.
+
+```bash
+npx paperclipai plugin install @kujolang/paperclip
+```
+
+Restart Paperclip if it is already running. Open a project, issue, or run and select the **Kujo** tab. The status panel should report that the runtime and all four bundled components are ready.
+
+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.
+
+See [Installation](docs/INSTALLATION.md) for upgrades, local development installs, and uninstall behavior.
+
+## Use
+
+Open the **Kujo** tab on a project or issue to:
+
+- generate a **Review Pack** for the working tree;
+- create a task-specific **Context Pack**;
+- capture bounded, redacted **Failure Evidence**.
+
+Agents can call four tools:
+
+| Tool | Use |
+| --- | --- |
+| `kujolang.paperclip:review-changes` | Measure change size and create a review handoff. |
+| `kujolang.paperclip:capture-failure` | Save supplied command output as redacted evidence. It never reruns the command. |
+| `kujolang.paperclip:get-context` | Select a bounded set of files for a task. |
+| `kujolang.paperclip:get-context-content` | Read safe content from files selected by an existing Context Pack. |
+
+Example agent requests:
+
+```text
+Use kujolang.paperclip:get-context with task "trace the OAuth callback" and depth "focused".
+Use kujolang.paperclip:review-changes after the edit and report the suggested tests as suggestions, not completed checks.
+If a check fails, use kujolang.paperclip:capture-failure with the command, exit code, and bounded log.
+```
+
+The content tool only reads files selected by the matching Context Pack. It rejects other paths, binary files, oversized files, traversal, and symlink escapes.
+
+See [Usage](docs/USAGE.md) for tool inputs, UI actions, artifact fields, and common workflows.
+
+## What it adds
+
+- **Review Pack** uses ChangeBucket to measure the change and PatchBrief to explain it.
+- **Failure Evidence** uses CaseFile to turn supplied logs into a reviewable record.
+- **Context Pack** uses Scent to select relevant files before an agent reads broadly.
+
+All four component snapshots are pinned, checksummed, and shipped in the package. The plugin does not fetch component code at runtime.
+
+## Compatibility
+
+| Package | Version |
+| --- | --- |
+| Paperclip host | `>=2026.824.1` |
+| `@paperclipai/plugin-sdk` | `2026.824.1` |
+| `@kujolang/kujo-runtime` | `1.2.2` |
+| Node.js | `>=24.11.0` |
+
+The npm package is `@kujolang/paperclip`. Its Paperclip manifest ID is `kujolang.paperclip` because manifest IDs do not accept npm scope syntax.
+
+## Configure
+
+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.
+
+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.
+
+## How it runs
+
+The worker resolves Kujo in this order:
+
+1. configured absolute binary;
+2. bundled `@kujolang/kujo-runtime` binary;
+3. an absolute `kujo` found on `PATH`, when allowed;
+4. a structured error with a repair hint.
+
+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.
+
+## Develop
+
+```bash
+npm ci --ignore-scripts
+npm run verify
+```
+
+`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.
+
+Read [AGENTS.md](AGENTS.md) before agent-assisted changes and [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request.
+
+## Documentation
+
+- [Documentation index](docs/README.md)
+- [Installation](docs/INSTALLATION.md)
+- [Usage](docs/USAGE.md)
+- [Configuration](docs/CONFIGURATION.md)
+- [Compatibility](docs/COMPATIBILITY.md)
+- [Architecture](docs/ARCHITECTURE.md)
+- [Threat model](docs/THREAT_MODEL.md)
+- [Security policy](SECURITY.md)
+- [Troubleshooting](docs/TROUBLESHOOTING.md)
+- [Release readiness](docs/RELEASE_READINESS.md)
+- [Operations](docs/OPERATIONS.md)
+- [Agent workflow example](examples/agent-workflow.md)
+
+## License
+
+MIT. Bundled Kujo components keep their canonical MIT licenses and recorded provenance.

package/SECURITY.md

@@ -0,0 +1,35 @@
+# Security policy
+
+## Report a vulnerability
+
+Use GitHub Security Advisories for `kujolang/paperclip`. Do not open a public issue with exploit details, credentials, private source, logs, or workspace paths.
+
+Include the affected version, impact, safe reproduction steps, and suggested mitigation when available.
+
+## Supported versions
+
+Security fixes apply to the latest tagged `0.1.x` release and `main`. Before `1.0`, a fix may require upgrading to the latest minor version instead of receiving a backport.
+
+## Operating model
+
+The plugin analyzes local Paperclip workspaces with bundled Kujo components. It requests no network, secret, issue-write, approval, budget, database, job, webhook, or arbitrary-folder capability.
+
+The plugin does not provide a sandbox. Only install it in a trusted Paperclip host. Treat generated Review, Failure Evidence, and Context Packs as sensitive project data.
+
+## Security boundaries
+
+- Paperclip supplies canonical workspaces; tools cannot choose raw workspace paths.
+- Workspace scans reject individual files over 25 MB and repositories with more than 100,000 Git-visible files before a component starts.
+- Child processes use fixed entrypoints, argument arrays, `shell: false`, a small environment, timeouts, output limits, and whole-process-tree termination.
+- Git runs without system or global configuration, hooks, external diff drivers, credential prompts, or file-system monitors.
+- Component checksums are verified before execution.
+- Context content is opt-in, restricted to selected files, bounded, and checked against traversal and symlink escape.
+- Stored artifacts are isolated by company, validated on read, checked against their entity and workspace, and cleared on request.
+- Disabled features cannot be invoked through tools, UI actions, or stored-artifact reads.
+- Generation and content-read events are written to the Paperclip activity log when the host accepts them.
+- Failure Evidence records supplied text and never runs the recorded command.
+- Redaction covers common credential shapes but cannot guarantee that every secret format is removed.
+
+The release pipeline audits production dependencies, verifies registry integrity and accepted licenses, emits a CycloneDX SBOM, attests the npm tarball, and publishes that exact tarball with npm provenance. Dependabot, dependency review, CodeQL, and the cross-platform compatibility matrix run in GitHub Actions.
+
+See [docs/THREAT_MODEL.md](docs/THREAT_MODEL.md) for assets, trust boundaries, abuse cases, and mitigations.

package/VERSION

@@ -0,0 +1 @@
+0.1.0

package/bundled/components/changebucket/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Kujolang <contact@kujolang.ai>
+
+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/bundled/components/changebucket/changebucket.kujo

@@ -0,0 +1,12 @@
+# ChangeBucket entrypoint.
+#
+# Thin wrapper: no logic here. Hand the user's arguments to the CLI module and
+# translate its return value into a process exit code.
+#
+# Run via the bin/changebucket wrapper:
+#   ./bin/changebucket <command> [arguments]
+
+from src.cli import main
+
+code := main(args())
+exit(code)

package/bundled/components/changebucket/src/analyze.kujo

@@ -0,0 +1,240 @@
+# ChangeBucket :: analyze
+#
+# The heart of the tool. It turns read-only git output into the structured
+# analysis model (summary + categories + per-file detail + risk level).
+# Nothing here mutates the repo. All multi-pass logic uses index/`while` loops
+# or single-`for` helpers so the module compiles under the checker.
+
+from src.classify import classify, category_order
+from src.diffsrc import is_repo, repo_root, resolve_refs, validate_diff, numstat_text, namestatus_text, untracked_list, is_binary_path, count_added_lines
+
+# Map a git name-status letter to a human status word.
+func status_word(letter) {
+    if letter == "A" {
+        return "added"
+    }
+    if letter == "D" {
+        return "deleted"
+    }
+    if letter == "R" {
+        return "renamed"
+    }
+    if letter == "C" {
+        return "copied"
+    }
+    return "modified"
+}
+
+# Fresh categories dict with every bucket present and empty.
+func init_cats() {
+    mut cats := {}
+    for name in category_order() {
+        cats[name] := []
+    }
+    return cats
+}
+
+# Record file `path` under each of its categories.
+func add_to_cats(cats, categories, path) {
+    for c in categories {
+        cats[c] := push(cats[c], path)
+    }
+    return cats
+}
+
+# Ingest `git diff --name-status` lines: seed each path with its status.
+func ingest_namestatus(order, info, text) {
+    mut ord := order
+    nul := parse_json("\"\\u0000\"")
+    fields := split(text, nul)
+    mut i := 0
+    while i + 1 < len(fields) {
+        status := fields[i]
+        path := fields[i + 1]
+        if status != "" && path != "" {
+            letter := substring(status, 0, 1)
+            if has_key(info, path) == 0 {
+                info[path] := {"path": path, "status": status_word(letter), "additions": 0, "deletions": 0, "binary": false}
+                ord = push(ord, path)
+            } else {
+                e := info[path]
+                e["status"] := status_word(letter)
+                info[path] := e
+            }
+        }
+        i = i + 2
+    }
+    return {"order": ord, "info": info}
+}
+
+# Ingest `git diff --numstat` lines: attach additions/deletions (or binary).
+func ingest_numstat(order, info, text) {
+    mut ord := order
+    nul := parse_json("\"\\u0000\"")
+    records := split(text, nul)
+    for record in records {
+        if record != "" {
+            cols := split(record, "\t")
+            adds := cols[0]
+            dels := cols[1]
+            # Only the first two tabs are separators; a path may itself contain
+            # tabs, so reconstruct it from all remaining fields.
+            path := join(slice(cols, 2, len(cols)), "\t")
+            binary := adds == "-" || dels == "-"
+            mut a := 0
+            mut d := 0
+            if binary == false {
+                a = parse_int(adds)
+                d = parse_int(dels)
+            }
+            if has_key(info, path) == 0 {
+                info[path] := {"path": path, "status": "modified", "additions": a, "deletions": d, "binary": binary}
+                ord = push(ord, path)
+            } else {
+                e := info[path]
+                e["additions"] := a
+                e["deletions"] := d
+                e["binary"] := binary
+                info[path] := e
+            }
+        }
+    }
+    return {"order": ord, "info": info}
+}
+
+# Ingest untracked files as additions (worktree mode only).
+func ingest_untracked(order, info, files, repo) {
+    mut ord := order
+    for path in files {
+        if path != "" && has_key(info, path) == 0 {
+            binary := is_binary_path(path)
+            mut a := 0
+            if binary == false {
+                a = count_added_lines(repo, path)
+            }
+            info[path] := {"path": path, "status": "added", "additions": a, "deletions": 0, "binary": binary}
+            ord = push(ord, path)
+        }
+    }
+    return {"order": ord, "info": info}
+}
+
+# A simple, documented blast-radius heuristic. This is "risk", not "quality".
+#   high   : >20 files, or >1000 churn, or any deletes, or generated touched
+#   low    : <=5 files, <=200 churn, no deletes, no dep/lock/ci/generated touched
+#   medium : everything in between
+export func risk_level(files_changed, churn, deleted, deps, locks, generated, ci) {
+    if files_changed > 20 || churn > 1000 || deleted > 0 || generated > 0 {
+        return "high"
+    }
+    if files_changed <= 5 && churn <= 200 && deleted == 0 && deps == 0 && locks == 0 && ci == 0 {
+        return "low"
+    }
+    return "medium"
+}
+
+# Walk the ordered file list, classify each, and roll up summary + categories.
+func build_model(repo, refs, order, info) {
+    mut cats := init_cats()
+    mut files := []
+    mut files_added := 0
+    mut files_modified := 0
+    mut files_deleted := 0
+    mut files_renamed := 0
+    mut binary_files := 0
+    mut lines_added := 0
+    mut lines_deleted := 0
+    mut i := 0
+    while i < len(order) {
+        p := order[i]
+        e := info[p]
+        categories := classify(p)
+        e["categories"] := categories
+        e["churn"] := e["additions"] + e["deletions"]
+        files = push(files, e)
+        cats = add_to_cats(cats, categories, p)
+
+        st := e["status"]
+        if st == "added" {
+            files_added = files_added + 1
+        }
+        if st == "modified" {
+            files_modified = files_modified + 1
+        }
+        if st == "deleted" {
+            files_deleted = files_deleted + 1
+        }
+        if st == "renamed" {
+            files_renamed = files_renamed + 1
+        }
+        if e["binary"] == true {
+            binary_files = binary_files + 1
+        }
+        lines_added = lines_added + e["additions"]
+        lines_deleted = lines_deleted + e["deletions"]
+        i = i + 1
+    }
+
+    churn := lines_added + lines_deleted
+    files_changed := len(order)
+    risk := risk_level(files_changed, churn, files_deleted, len(cats["dependency_manifests"]), len(cats["lockfiles"]), len(cats["generated"]), len(cats["ci"]))
+
+    summary := {
+        "files_changed": files_changed,
+        "files_added": files_added,
+        "files_modified": files_modified,
+        "files_deleted": files_deleted,
+        "files_renamed": files_renamed,
+        "binary_files": binary_files,
+        "lines_added": lines_added,
+        "lines_deleted": lines_deleted,
+        "total_churn": churn,
+        "risk_level": risk
+    }
+
+    return {
+        "base": refs["base_label"],
+        "head": refs["head_label"],
+        "generated_at": now_utc(),
+        "summary": summary,
+        "categories": cats,
+        "files": files,
+        "budget": {"checked": false, "passed": true, "failures": []}
+    }
+}
+
+# Top-level: produce the analysis model for `repo` over the requested refs, or
+# {"error": "..."} when the directory is not a git repository.
+export func analyze(repo, base_flag, head_flag) {
+    if is_repo(repo) == false {
+        return {"error": "not a git repository: " + repo}
+    }
+    root := repo_root(repo)
+    refs := resolve_refs(root, base_flag, head_flag)
+    if has_key(refs, "error") == 1 {
+        return {"error": refs["error"]}
+    }
+    diff_error := validate_diff(root, refs)
+    if diff_error != "" {
+        return {"error": diff_error}
+    }
+
+    mut order := []
+    mut info := {}
+
+    ns := ingest_namestatus(order, info, namestatus_text(root, refs))
+    order = ns["order"]
+    info = ns["info"]
+
+    num := ingest_numstat(order, info, numstat_text(root, refs))
+    order = num["order"]
+    info = num["info"]
+
+    if refs["include_untracked"] == true {
+        ut := ingest_untracked(order, info, untracked_list(root), root)
+        order = ut["order"]
+        info = ut["info"]
+    }
+
+    return build_model(root, refs, order, info)
+}

package/bundled/components/changebucket/src/budget.kujo

@@ -0,0 +1,92 @@
+# ChangeBucket :: budget
+#
+# Deterministic threshold checking against an analysis model. A budget config is
+# a plain dict (numeric limits default to null = unlimited; boolean bans default
+# to false). `evaluate` returns the model with its `budget` block filled in:
+#   {"checked": true, "passed": bool, "failures": [strings]}
+
+from src.util import commas, display_path
+
+# A budget config with everything off. The CLI overlays user flags onto this.
+export func empty_config() {
+    return {
+        "max_files": null,
+        "max_churn": null,
+        "max_additions": null,
+        "max_deletions": null,
+        "no_deletes": false,
+        "no_dependency_changes": false,
+        "no_lockfile_changes": false,
+        "no_config_changes": false,
+        "no_generated_changes": false
+    }
+}
+
+# True if the user actually set any budget constraint. Used to decide whether to
+# show the Budget section on the default (non-`check`) command.
+export func has_constraints(cfg) {
+    if type(cfg["max_files"]) != "null" || type(cfg["max_churn"]) != "null" {
+        return true
+    }
+    if type(cfg["max_additions"]) != "null" || type(cfg["max_deletions"]) != "null" {
+        return true
+    }
+    if cfg["no_deletes"] == true || cfg["no_dependency_changes"] == true {
+        return true
+    }
+    if cfg["no_lockfile_changes"] == true || cfg["no_config_changes"] == true {
+        return true
+    }
+    if cfg["no_generated_changes"] == true {
+        return true
+    }
+    return false
+}
+
+# Append a "label: value > max limit" failure when a numeric ceiling is exceeded.
+func check_max(failures, label, value, limit) {
+    if type(limit) == "null" {
+        return failures
+    }
+    if value > limit {
+        return push(failures, label + ": " + commas(value) + " > max " + commas(limit))
+    }
+    return failures
+}
+
+# Append one failure per file in a banned category.
+func check_banned(failures, banned, paths, label) {
+    if banned != true {
+        return failures
+    }
+    mut out := failures
+    for p in paths {
+        out = push(out, label + ": " + display_path(p))
+    }
+    return out
+}
+
+# Evaluate `cfg` against `model`, mutating and returning the model's budget block.
+export func evaluate(model, cfg) {
+    s := model["summary"]
+    cats := model["categories"]
+    mut failures := []
+
+    failures = check_max(failures, "Changed files", s["files_changed"], cfg["max_files"])
+    failures = check_max(failures, "Total churn", s["total_churn"], cfg["max_churn"])
+    failures = check_max(failures, "Lines added", s["lines_added"], cfg["max_additions"])
+    failures = check_max(failures, "Lines deleted", s["lines_deleted"], cfg["max_deletions"])
+
+    if cfg["no_deletes"] == true && s["files_deleted"] > 0 {
+        failures = push(failures, "Deletes not allowed: " + commas(s["files_deleted"]) + " file(s) deleted")
+    }
+
+    failures = check_banned(failures, cfg["no_dependency_changes"], cats["dependency_manifests"], "Dependency manifest changed")
+    failures = check_banned(failures, cfg["no_lockfile_changes"], cats["lockfiles"], "Lockfile changed")
+    failures = check_banned(failures, cfg["no_config_changes"], cats["config"], "Config file changed")
+    failures = check_banned(failures, cfg["no_generated_changes"], cats["generated"], "Generated file changed")
+
+    passed := len(failures) == 0
+    model["budget"] := {"checked": true, "passed": passed, "failures": failures}
+    return model
+}