@varman96/paper 1.0.1 → 1.0.3
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 +2 -0
- package/dist/paper.js +12 -12
- package/package.json +2 -2
package/README.md
CHANGED
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.3",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://paper-ai.paperhq.workers.dev/",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
|
|
|
@@ -22,15 +22,15 @@ Report: .paper/incident_report.md
|
|
|
22
22
|
paper shelf Move the active Incident Report out of the workspace
|
|
23
23
|
|
|
24
24
|
--help Show this help
|
|
25
|
-
--version Show the version`,
|
|
25
|
+
--version Show the version`,b=["<!-- paper:start -->","## Paper Incident Workflow","","When `.paper/incident_report.md` exists, read it before investigating.","","Treat the Incident Report as the current evidence anchor, not as infallible truth. Use it to establish the known failure boundary, then inspect the repository, runtime, tests, configuration, and other source-of-truth evidence as needed.","","Diagnose the issue using this trace:","","### 1. Establish the Failing Invariant","","Identify the exact boundary contract that was violated.","","State:","","Invariant Expected:","The concrete behavior or state that should have held.","","Invariant Observed:","The concrete behavior or state actually observed.","","Use precise system evidence where available:","- exit codes","- status codes","- errno","- ports","- file paths","- symbols","- stack frames","- environment values","- process state","- exact command output","","Do not replace concrete evidence with vague summaries.","","### 2. State Elimination","","Shrink the search space by explicitly ruling out competing explanations using verified evidence.","","For each relevant factor, state whether it is:","- confirmed working","- confirmed failing","- still unverified","","Examples:","- config parsed successfully","- network route reachable","- dependency present or missing","- process listening or not listening","- expected environment variable present or absent","","Do not mark a hypothesis ruled out without evidence.","","Do not repeat theories already ruled out by the Incident Report unless new evidence justifies reopening them.","","### 3. Single-Point Attribution","","Narrow the diagnosis to the smallest confirmed fault boundary.","","State:","","Fault Location:","The exact file, line, symbol, process, dependency, configuration value, environment delta, or runtime boundary responsible.","","Mechanism:","The concrete way that fault caused the observed invariant violation.","","Do not invent a root cause if the evidence only supports a narrower failure boundary.","","If the mechanism is not yet verified, label it as unverified and continue investigating.","","Newer source-of-truth evidence overrides stale or incorrect Incident Report content.","","### 4. Proposed Action Packet \u2014 Zero Execution","","Once the failure is sufficiently explained, STOP before remediation.","","Do not:","- modify files","- start or stop services","- change configuration","- install dependencies","- run a fix","- apply a patch","- mutate the environment","","unless the user explicitly asked for remediation.","","Report:","","What I found:","A concise diagnosis grounded in the Incident Report and verified evidence gathered afterward.","","Proposed fix:","The smallest intervention that addresses the confirmed mechanism.","","Diff preview:","Describe the expected code/config change if applicable. Do not apply it.","","Verification test:","Name the smallest test or command that would verify the proposed fix.","","Clearly distinguish:","- evidence already present in the Incident Report","- findings established during investigation","- hypotheses that remain unverified","","Once the current failure is sufficiently explained, stop widening the investigation unless new evidence connects another issue to the same failure.","","Important behavior:","- The agent may inspect the repo/runtime normally.","- The Incident Report is not the only source of truth.","- The agent must not hallucinate missing telemetry.","- The agent must not convert an unverified hypothesis into a confirmed diagnosis.","- The agent must not execute remediation unless explicitly asked.","- The diagnostic trace is investigative structure, not verbose prose. Keep each section concise and evidence-based.","<!-- paper:end -->"].join(`
|
|
26
26
|
`),d=class extends Error{constructor(t,n,r,s){super(n),this.name="PaperCliError",this.causeLabel=t,this.state=r,this.directive=s}};function N(e){return e instanceof d?[e.causeLabel,e.message,"",e.state,"",e.directive].join(`
|
|
27
27
|
`):["PAPER OPERATION FAILED",e?.message||"Paper encountered an unclassified local operation failure.","","Paper stopped before the requested operation completed.","","Resolve the reported local error and run Paper again."].join(`
|
|
28
|
-
`)}function Q({modulePath:e=Y(import.meta.url),invokedPath:t=process.argv[1],resolvePath:n=V.native}={}){if(!t)return{isCli:!1,startupFailure:!1};try{return{isCli:n(g(e))===n(g(t)),startupFailure:!1}}catch{let r=k(e).toLowerCase(),s=k(t).toLowerCase();return{isCli:!1,startupFailure:r===s}}}async function ee(e){try{let t=await F(e);return t.isDirectory()||t.isFile()}catch{return!1}}async function x(e=process.cwd()){let t=g(e);for(;;){if(await ee(o(t,".git")))return t;let n=f(t);if(n===t)return g(e);t=n}}async function v(e,t){try{let n=await F(e);return t==="directory"?n.isDirectory():t==="file"?n.isFile():!0}catch{return!1}}async function m(e){try{if((await q(e)).isSymbolicLink())throw new Error(`Refusing to write through a symbolic link: ${e}`)}catch(t){if(t.code!=="ENOENT")throw t}}async function te(e){let t=[],n=["AGENTS.md","CLAUDE.md","GEMINI.md",o(".github","copilot-instructions.md"),".cursorrules",o(".cursor","rules.md"),o(".cursor","instructions.md")];for(let r of n)await v(o(e,r),"file")&&t.push(o(e,r));return await v(o(e,".cursor","rules"),"directory")&&t.push(o(e,".cursor","rules","paper.mdc")),t.length?t:[o(e,"AGENTS.md")]}function ne(e){let t=/<!-- paper:start -->[\s\S]*?<!-- paper:end -->/g;if(e.match(t)?.length){let r=0,s=e.replace(t,()=>r++===0?
|
|
28
|
+
`)}function Q({modulePath:e=Y(import.meta.url),invokedPath:t=process.argv[1],resolvePath:n=V.native}={}){if(!t)return{isCli:!1,startupFailure:!1};try{return{isCli:n(g(e))===n(g(t)),startupFailure:!1}}catch{let r=k(e).toLowerCase(),s=k(t).toLowerCase();return{isCli:!1,startupFailure:r===s}}}async function ee(e){try{let t=await F(e);return t.isDirectory()||t.isFile()}catch{return!1}}async function x(e=process.cwd()){let t=g(e);for(;;){if(await ee(o(t,".git")))return t;let n=f(t);if(n===t)return g(e);t=n}}async function v(e,t){try{let n=await F(e);return t==="directory"?n.isDirectory():t==="file"?n.isFile():!0}catch{return!1}}async function m(e){try{if((await q(e)).isSymbolicLink())throw new Error(`Refusing to write through a symbolic link: ${e}`)}catch(t){if(t.code!=="ENOENT")throw t}}async function te(e){let t=[],n=["AGENTS.md","CLAUDE.md","GEMINI.md",o(".github","copilot-instructions.md"),".cursorrules",o(".cursor","rules.md"),o(".cursor","instructions.md")];for(let r of n)await v(o(e,r),"file")&&t.push(o(e,r));return await v(o(e,".cursor","rules"),"directory")&&t.push(o(e,".cursor","rules","paper.mdc")),t.length?t:[o(e,"AGENTS.md")]}function ne(e){let t=/<!-- paper:start -->[\s\S]*?<!-- paper:end -->/g;if(e.match(t)?.length){let r=0,s=e.replace(t,()=>r++===0?b:"");return{next:s,changed:s!==e}}return{next:e?`${e}${e.endsWith(`
|
|
29
29
|
`)?`
|
|
30
30
|
`:`
|
|
31
31
|
|
|
32
|
-
`}${
|
|
33
|
-
`:`${
|
|
32
|
+
`}${b}
|
|
33
|
+
`:`${b}
|
|
34
34
|
`,changed:!0}}async function re(e=process.cwd()){let t=await x(e),n=await te(t),r=[],s=[];for(let a of n){await m(a),await m(f(a)),await m(f(f(a)));let i="";try{i=await K(a,"utf8")}catch(u){if(u.code!=="ENOENT")throw u}let{next:c,changed:l}=ne(i);l&&(await P(f(a),{recursive:!0}),await M(a,c,"utf8"),r.push(a),i||s.push(a))}return{repoRoot:t,targetPaths:n,changedPaths:r,created:s.length>0,changed:r.length>0}}async function ie(e,t){let n=o(e,".paper","incident_report.md");return await m(o(e,".paper")),await m(n),await P(f(n),{recursive:!0}),await M(n,t,"utf8"),n}function se(e=process.env,t=O()){return t==="win32"?e.LOCALAPPDATA||o($(),"AppData","Local","Paper"):o(e.XDG_DATA_HOME||o($(),".local","share"),"Paper")}function ae(e,t=process.env,n=O()){let r=Z("sha256").update(g(e)).digest("hex").slice(0,16);return o(se(t,n),"shelf",r)}function oe(e=new Date){return e.toISOString().replace(/[:.]/g,"-")}async function ce(e,t){let n=0;for(;;){let r=o(e,`${t}${n?`-${n}`:""}.md`);if(!await v(r,"file"))return r;n+=1}}async function de(){let e=await x(),t=o(e,".paper","incident_report.md");if(!await v(t,"file"))throw new d("NO ACTIVE INCIDENT","Paper could not find an active Incident Report.","No files were changed.","Run `paper run <command>` to capture a failure first.");let n=ae(e),r=await ce(n,oe());try{await P(n,{recursive:!0}),await X(t,r)}catch(s){throw new d("INCIDENT SHELF FAILED",`Paper could not move the Incident Report out of the workspace${s?.code?` (${s.code})`:"."}`,"The active Incident Report was preserved in the workspace.","Restore access to the Paper shelf location and run `paper shelf` again.")}process.stdout.write(`INCIDENT SHELVED
|
|
35
35
|
Moved the active Incident Report out of the workspace.
|
|
36
36
|
|
|
@@ -41,24 +41,24 @@ ${r}
|
|
|
41
41
|
${a} exited with ${c}.
|
|
42
42
|
|
|
43
43
|
Paper captured the failure and persisted the Incident Report at \`${s}\`.
|
|
44
|
-
`)}}var ge=[/\b(?:error|fatal|exception|panic|failed|failure|traceback|segmentation fault|command not found|exited with code)\b|ERR!/i,/\b(?:HTTP\/\d(?:\.\d)?\s+)?[45]\d{2}\b/i,/\b(?:exit(?:ed| status| code)?|status code)\s*[:=]?\s*[1-9]\d*/i],we=/HTTP\/\d(?:\.\d)?\s+[1-5]\d{2}\b|\bstatus(?: code)?\s*[:=]?\s*[1-5]\d{2}\b/i,ve=/\b(?:exited with code|exit(?: status| code)?|status code)\s*[:=]?\s*[1-9]\d*/i,W=/^\s*(?:at\s+.+|File\s+["'].+["'],\s*line\s+\d+|[\w.]+\.[\w$]+\([^)]*:\d+(?::\d+)?\))/i,_=/^\s*(?:[$>]|(?:curl|wget|git|docker|kubectl|wrangler|npm|npx|node|python(?:\d+)?|pytest|cargo|go|dotnet|java|bun|deno|yarn|pnpm)\b)/i,
|
|
44
|
+
`)}}var ge=[/\b(?:error|fatal|exception|panic|failed|failure|traceback|segmentation fault|command not found|exited with code)\b|ERR!/i,/\b(?:HTTP\/\d(?:\.\d)?\s+)?[45]\d{2}\b/i,/\b(?:exit(?:ed| status| code)?|status code)\s*[:=]?\s*[1-9]\d*/i],we=/HTTP\/\d(?:\.\d)?\s+[1-5]\d{2}\b|\bstatus(?: code)?\s*[:=]?\s*[1-5]\d{2}\b/i,ve=/\b(?:exited with code|exit(?: status| code)?|status code)\s*[:=]?\s*[1-9]\d*/i,W=/^\s*(?:at\s+.+|File\s+["'].+["'],\s*line\s+\d+|[\w.]+\.[\w$]+\([^)]*:\d+(?::\d+)?\))/i,_=/^\s*(?:[$>]|(?:curl|wget|git|docker|kubectl|wrangler|npm|npx|node|python(?:\d+)?|pytest|cargo|go|dotnet|java|bun|deno|yarn|pnpm)\b)/i,ye=/\b(?:node(?:\.js)?|npm|npx|pnpm|yarn|bun|deno|python(?:\d+)?|pytest|ruby|java|dotnet|cargo|rustc|go version|windows|linux|darwin|macos|runtime|version)\b/i,be=/(?:[A-Za-z]:[\\/][^\s,;()[\]{}]+|(?:\.{0,2}[\\/])?[A-Za-z0-9_.-]+(?:[\\/][A-Za-z0-9_.-]+)+\.[A-Za-z0-9_.-]+)/g,A=/^\s*(?:\+\s*)?(?:CategoryInfo|FullyQualifiedErrorId)\b/i,S=/^\s*At line:\d+ char:\d+\s*$/i,C=/^\s*(?:\+\s*)?~+\s*$/,D=/^\s*\+\s*npm(?:\.cmd)?\b/i,Pe=/^\s*\+\s*curl(?:\.exe)?\b/i,xe=/^\s*\|\s*(?:node|npm|npx)\b/i,j=/^\s*(?:npm(?:\.cmd)?|curl(?:\.exe)?)\s*:\s+/i,Ee=/^\s*[a-z]:\/\//i;function Ie(e=""){let t=String(e??""),n=t.replace(/\r\n?/g,`
|
|
45
45
|
`).split(`
|
|
46
46
|
`);if(!(n.some(i=>A.test(i))&&n.some(i=>j.test(i))))return t;let s=[],a=!1;for(let i of n){if(A.test(i)){a=!0;continue}if(a){if(!i.trim()){a=!1,s.push(i);continue}if(S.test(i)||C.test(i)||D.test(i))continue;if(W.test(i)||_.test(i))a=!1;else continue}if(S.test(i)||C.test(i)||D.test(i)||xe.test(i))continue;if(Pe.test(i)){let l=i.replace(/^\s*\+\s*/,"");s.at(-1)!==l&&s.push(l);continue}if(Ee.test(i))continue;let c=i.replace(j,"");s.at(-1)!==c&&s.push(c)}return s.join(`
|
|
47
|
-
`)}function h(e){return[...new Set(e.map(t=>t.trim()).filter(Boolean))]}function Re(e){return h([...e.matchAll(
|
|
47
|
+
`)}function h(e){return[...new Set(e.map(t=>t.trim()).filter(Boolean))]}function Re(e){return h([...e.matchAll(be)].map(([t])=>t.replace(/[.:]+$/,"")).filter(t=>!/^HTTP\/\d(?:\.\d)?$/i.test(t)&&!/^[a-z]:\/\//i.test(t)))}function Te(e=""){let t=Ie(e),r=t.replace(/\r\n?/g,`
|
|
48
48
|
`).split(`
|
|
49
|
-
`).filter(p=>p.trim()),s=h(r.filter(p=>ge.some(G=>G.test(p)))),a=h(r.filter(p=>W.test(p))),i=h(r.filter(p=>_.test(p))),c=h(r.filter(p=>
|
|
50
|
-
`),
|
|
49
|
+
`).filter(p=>p.trim()),s=h(r.filter(p=>ge.some(G=>G.test(p)))),a=h(r.filter(p=>W.test(p))),i=h(r.filter(p=>_.test(p))),c=h(r.filter(p=>ye.test(p))),l=h(r.filter(p=>we.test(p))),u=h(r.filter(p=>ve.test(p))),w=Re(t),E=h([...s,...a]).join(`
|
|
50
|
+
`),y=i.join(`
|
|
51
51
|
`),z=w.length?`${w.join(`
|
|
52
52
|
`)}
|
|
53
53
|
|
|
54
54
|
${t}`:t;return{"what-failing":s.join(`
|
|
55
55
|
`),"observed-at-boundary":s.join(`
|
|
56
|
-
`),"input-payload":
|
|
56
|
+
`),"input-payload":y,"output-error":E,origin:y,"first-confirmed-divergence":s[0]||a[0]||"","runtime-environment-hops":c.join(`
|
|
57
57
|
`),"exit-code":u.join(`
|
|
58
58
|
`),"stderr-stack-trace":E,"status-codes":l.join(`
|
|
59
|
-
`),commands:
|
|
59
|
+
`),commands:y,"runtime-versions":c.join(`
|
|
60
60
|
`),"other-receipts":z}}function $e(e=""){return R(Te(e))}var L=Q();if(L.startupFailure)process.stderr.write(`${N(new d("CLI ENTRYPOINT MISMATCH","Paper loaded, but the executable path could not be resolved to the active CLI entrypoint.","No target command was started.","Reinstall or relink Paper and run the command again."))}
|
|
61
61
|
`),process.exitCode=1;else if(L.isCli)try{let e=process.argv.slice(2);if(e[0]==="--help")process.stdout.write(`${J}
|
|
62
62
|
`);else if(e[0]==="--version")process.stdout.write(`${T.version}
|
|
63
63
|
`);else if(e[0]==="shelf"&&e.length===1)await de();else if(e.length){if(e[0]!=="run")throw new d("INVALID COMMAND","Paper expected `run` before the target command.","No target command was started.","Use `paper run <command>`.");if(e.length===1)throw new d("NO COMMAND","Paper needs a command to capture.","No target command was started.","Use `paper run <command>`. ");await me(e[1],e.slice(2))}else throw new d("NO COMMAND","Paper needs a command to capture.","No target command was started.","Use `paper run <command>`.")}catch(e){process.stderr.write(`${N(e)}
|
|
64
|
-
`),process.exitCode=1}export{
|
|
64
|
+
`),process.exitCode=1}export{b as MANAGED_AGENT_RULES_BLOCK,d as PaperCliError,$e as buildTerminalPacket,te as detectAgentInstructionPaths,re as ensureManagedAgentRules,Te as extractTerminalPacket,x as findRepoRoot,N as formatPaperCliError,Ie as normalizeTerminalOutput,Q as resolveCliEntrypoint,ae as shelfPathForRepo,ie as writeIncidentReport};
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@varman96/paper",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.3",
|
|
4
4
|
"description": "Paper captures command failures in a structured Incident Report for coding-agent investigation.",
|
|
5
5
|
"main": "dist/paper.js",
|
|
6
6
|
"bin": {
|
|
@@ -38,7 +38,7 @@
|
|
|
38
38
|
"bugs": {
|
|
39
39
|
"url": "https://github.com/varman96/paper/issues"
|
|
40
40
|
},
|
|
41
|
-
"homepage": "https://
|
|
41
|
+
"homepage": "https://paper-ai.paperhq.workers.dev/",
|
|
42
42
|
"devDependencies": {
|
|
43
43
|
"@biomejs/biome": "2.5.14",
|
|
44
44
|
"esbuild": "^0.28.1",
|