@varman96/paper 1.0.0 → 1.0.1
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.
- package/README.md +29 -121
- package/dist/paper.js +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,148 +1,56 @@
|
|
|
1
1
|
# Paper
|
|
2
2
|
|
|
3
|
-
Paper
|
|
3
|
+
Paper captures command failures in a structured Incident Report for coding-agent investigation.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Primary workflow: Install -> Capture -> Ask.
|
|
6
6
|
|
|
7
|
-
##
|
|
7
|
+
## Install
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
- **Copy for AI**: Generates the packet locally in the browser and copies it for use in the AI coding tool of your choice.
|
|
12
|
-
- **Note Management**: Create, delete, switch between notes, and clear sample notes. Notes auto-save to browser local storage.
|
|
13
|
-
- **Markdown Export**: Export notes directly to `.md` files.
|
|
14
|
-
- **Local-first workflow**: The packet builder does not require an AI call or backend persistence.
|
|
15
|
-
|
|
16
|
-
---
|
|
17
|
-
|
|
18
|
-
## System Architecture
|
|
19
|
-
|
|
20
|
-
Paper consists of a static client-side application and API endpoints deployed through a Cloudflare Worker with static assets. The public landing page is served at `/`, and the packet builder is served at `/app/`.
|
|
21
|
-
|
|
22
|
-
```
|
|
23
|
-
paper/
|
|
24
|
-
├── index.html # Public landing page
|
|
25
|
-
├── app/
|
|
26
|
-
│ └── index.html # Manual packet fallback shell served at /app/
|
|
27
|
-
├── styles.css # Application styling
|
|
28
|
-
├── app.js # Application entry point and module coordination
|
|
29
|
-
├── js/
|
|
30
|
-
│ ├── debug-packet.js # Shared canonical packet schema and Markdown generator
|
|
31
|
-
│ ├── state.js # Central application state and getters
|
|
32
|
-
│ ├── storage.js # LocalStorage persistence and note schema creation
|
|
33
|
-
│ ├── editor.js # Block editor management, input handling, and character caps
|
|
34
|
-
│ ├── formatting.js # Selection toolbar and inline formatting commands
|
|
35
|
-
│ ├── manual/
|
|
36
|
-
│ │ └── debug-packet.js # Retained manual fallback packet UI logic
|
|
37
|
-
│ ├── notes.js # Note list management, title derivation, and export
|
|
38
|
-
│ ├── mobile.js # Mobile navigation drawer and responsive panels
|
|
39
|
-
│ └── utils.js # HTML sanitization and string helpers
|
|
40
|
-
├── legacy/
|
|
41
|
-
│ └── review/
|
|
42
|
-
│ ├── review.js # Dormant legacy Review coordination
|
|
43
|
-
│ └── critique-ui.js # Dormant legacy Review rendering
|
|
44
|
-
├── scripts/
|
|
45
|
-
│ ├── build-assets.js # Builds the root + /app/ static asset layout
|
|
46
|
-
│ └── paper.js # Local stdin CLI ingestion and deterministic extraction
|
|
47
|
-
├── .paper/
|
|
48
|
-
│ └── incident_report.md # Canonical investigative report template
|
|
49
|
-
├── worker.js # Routes /api/* before static assets
|
|
50
|
-
└── api/
|
|
51
|
-
└── lib/
|
|
52
|
-
├── gemini.js # Gemini API client with retry logic
|
|
53
|
-
├── rate-limit.js # Sliding-window IP rate limiter
|
|
54
|
-
├── review-prompt.js# System and user prompt construction
|
|
55
|
-
└── review-schema.js# Input normalization and response parsing
|
|
9
|
+
```bash
|
|
10
|
+
npm install -g @varman96/paper
|
|
56
11
|
```
|
|
57
12
|
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
---
|
|
61
|
-
|
|
62
|
-
## How It Works
|
|
13
|
+
## Use
|
|
63
14
|
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
- When the user types in the editor, DOM nodes are parsed and serialized into blocks.
|
|
67
|
-
- Notes are stored in the browser's `localStorage` under the key `paper.notes.v1`.
|
|
68
|
-
- The document title is automatically inferred from the first line of text unless manually modified by the user.
|
|
69
|
-
- Document editing and storage do not impose an AI-driven character limit.
|
|
70
|
-
|
|
71
|
-
### 2. The Incident Report Workflow
|
|
72
|
-
|
|
73
|
-
1. **Capture**: Collect runtime evidence in the CLI, incident template, or manual fallback.
|
|
74
|
-
2. **Structure**: Organize it in investigative order from Scope through Next Test.
|
|
75
|
-
3. **Generate Markdown**: Generate one deterministic packet locally.
|
|
76
|
-
4. **Copy for AI**: Copy the packet into Claude, Cursor, Codex, ChatGPT, or Gemini.
|
|
77
|
-
|
|
78
|
-
### 3. Terminal-first prototype
|
|
79
|
-
|
|
80
|
-
The local prototype accepts stdin and emits the same deterministic packet format without making model, backend, or network calls:
|
|
15
|
+
Run the command that is failing:
|
|
81
16
|
|
|
82
17
|
```bash
|
|
83
|
-
|
|
18
|
+
paper run <command>
|
|
84
19
|
```
|
|
85
20
|
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
### 4. Retired sharing
|
|
89
|
-
|
|
90
|
-
Document sharing is not part of the active application. The historical implementation is preserved under `legacy/sharing/` for reference and emergency recovery only; it must not be imported or published as an asset. Old share fragments are ignored and `/api/share` returns the normal unknown-API 404.
|
|
91
|
-
|
|
92
|
-
---
|
|
21
|
+
Paper runs the command normally. If it fails, Paper writes the captured evidence to `.paper/incident_report.md`.
|
|
93
22
|
|
|
94
|
-
|
|
23
|
+
Ask your coding agent:
|
|
95
24
|
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
## Running Locally
|
|
101
|
-
|
|
102
|
-
To run Paper locally with functional API routes:
|
|
103
|
-
|
|
104
|
-
1. Configure `.dev.vars` with the required local secrets.
|
|
105
|
-
|
|
106
|
-
2. Start the existing Cloudflare development server:
|
|
107
|
-
|
|
108
|
-
```bash
|
|
109
|
-
npx.cmd wrangler dev
|
|
110
|
-
```
|
|
25
|
+
```text
|
|
26
|
+
Diagnose the current failure.
|
|
27
|
+
```
|
|
111
28
|
|
|
112
|
-
|
|
29
|
+
The active Incident Report gives supported coding agents an evidence anchor, so you do not need to reconstruct the failure context.
|
|
113
30
|
|
|
114
|
-
For
|
|
31
|
+
For a resolved incident, move the active report out of the workspace:
|
|
115
32
|
|
|
116
33
|
```bash
|
|
117
|
-
|
|
34
|
+
paper shelf
|
|
118
35
|
```
|
|
119
36
|
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
## Issuing an Alpha Access Link
|
|
123
|
-
|
|
124
|
-
Use the trusted local issuer for a manually approved tester. It requires only an operator label and defaults to production D1 and `https://paper-ai.paperhq.workers.dev`:
|
|
37
|
+
## Commands
|
|
125
38
|
|
|
126
39
|
```bash
|
|
127
|
-
|
|
40
|
+
paper run <command>
|
|
41
|
+
paper shelf
|
|
42
|
+
paper --help
|
|
43
|
+
paper --version
|
|
128
44
|
```
|
|
129
45
|
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
When diagnosing an operational failure, consult the repository's [observed operator error reference](docs/operator-errors.md) before changing the Alpha access implementation.
|
|
133
|
-
|
|
134
|
-
**CJ Protocol** is the pre-send production verification gate: an invite URL is released only after the production Worker confirms that the exact invite is currently redeemable without consuming it. The issuer sends the exact token and returned credential ID to the Worker's same-origin verification route, where the token is hashed and checked through the same active-state validation used before redemption. Only a `204` response writes the complete private URL to stdout. Progress and diagnostics go to stderr, so failed verification leaves stdout empty. Send the URL directly to the tester; do not open it for them or paste it into logs or tickets. It contains a cryptographically random token, with only its hash stored in D1. No email, signup row, Turnstile, or email delivery is involved in manual issuance.
|
|
135
|
-
|
|
136
|
-
Invites expire after **24 hours** and are atomically single-use. The tester clicks **Open Paper** in their chosen browser; merely loading the invitation page does not consume it. Successful redemption creates the existing secure, HttpOnly, SameSite=Lax 30-day session. An already-authorized browser resumes `/app/` without consuming another invitation. Other browsers need their own fresh invite. Re-run the issuer for a replacement if required; it does not revoke existing sessions.
|
|
137
|
-
|
|
138
|
-
### Release prerequisite
|
|
139
|
-
|
|
140
|
-
Before issuing access to an untrusted tester, follow [Alpha security operations](docs/alpha-security-operations.md): credential-level revocation, migration `0003`, required durable Review ceilings, and production/legacy deployment checks. The issuer prints the credential ID to stderr for operator records; retain it without the bearer link. `npm.cmd run alpha:revoke -- --credential-id <id>` invalidates both the invite and its derived session and confirms the exact row. Labels are not unique identifiers.
|
|
141
|
-
|
|
142
|
-
Before the first label-only production invite, apply `migrations/0002_manual_alpha_invites.sql` through the normal D1 migration workflow, then deploy the matching Worker and assets. The migration rebuilds only the credential child table to permit a label in place of a signup reference, preserving existing credentials and sessions. The new Worker, including `/api/alpha/invite/verify`, must be live before using the updated issuer; an older deployment will make verification fail closed and release no link. Applying this migration or deploying is a separate, explicitly authorized release step.
|
|
46
|
+
## How it works
|
|
143
47
|
|
|
144
|
-
|
|
48
|
+
- Local CLI for capturing failed-command evidence.
|
|
49
|
+
- Structured Incident Report at `.paper/incident_report.md`.
|
|
50
|
+
- Evidence anchor for coding-agent investigation.
|
|
51
|
+
- No model API calls.
|
|
52
|
+
- No command-output upload.
|
|
145
53
|
|
|
146
|
-
|
|
54
|
+
## License
|
|
147
55
|
|
|
148
|
-
|
|
56
|
+
PolyForm Shield License 1.0.0
|
package/dist/paper.js
CHANGED
|
@@ -9,7 +9,7 @@ ${s.join(`
|
|
|
9
9
|
|
|
10
10
|
${t.join(`
|
|
11
11
|
|
|
12
|
-
`)}`:""}`}var T={name:"@varman96/paper",version:"1.0.
|
|
12
|
+
`)}`:""}`}var T={name:"@varman96/paper",version:"1.0.1",description:"Paper captures command failures in a structured Incident Report for coding-agent investigation.",main:"dist/paper.js",bin:{paper:"./dist/paper.js"},files:["dist/paper.js","README.md","LICENSE"],directories:{test:"test"},scripts:{"alpha:issue":"node scripts/issue-alpha-access.js","alpha:revoke":"node scripts/revoke-alpha-access.js","fail:test":"node scripts/fail-test.js",paper:"node scripts/paper.js","build:cli":"node scripts/build-cli.js",prepack:"npm run build:cli","deploy:production":"wrangler deploy --env production",test:"node test/run-tests.js","test:fast":"node test/run-tests.js --fast","test:browser":"node test/run-tests.js --browser","test:alpha-browser":"node test/alpha-access.browser.js"},repository:{type:"git",url:"git+https://github.com/varman96/paper.git"},keywords:[],author:"",license:"SEE LICENSE IN LICENSE",type:"module",bugs:{url:"https://github.com/varman96/paper/issues"},homepage:"https://github.com/varman96/paper#readme",devDependencies:{"@biomejs/biome":"2.5.14",esbuild:"^0.28.1",wrangler:"^4.132.0"}};var J=`Paper captures a failed command and writes a local Incident Report.
|
|
13
13
|
|
|
14
14
|
Usage: paper run <command>
|
|
15
15
|
|