paper-mono 0.62.0
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/CHANGELOG.md +21 -0
- package/DEPENDENCIES.json +143 -0
- package/LICENSE +21 -0
- package/README.md +138 -0
- package/SAFETY.md +27 -0
- package/THIRD_PARTY_NOTICES.md +244 -0
- package/bin/chunks/chunk-BGKLQ5Y6.js +55 -0
- package/bin/chunks/chunk-I4P43IZS.js +171 -0
- package/bin/chunks/chunk-JCO37BXY.js +31 -0
- package/bin/chunks/chunk-UHVY2TIH.js +3264 -0
- package/bin/chunks/chunk-ZX4GFXSY.js +37 -0
- package/bin/chunks/doctor-7DE4ASQO.js +355 -0
- package/bin/chunks/main-NQIGPQXK.js +23401 -0
- package/bin/chunks/owner-commands-MWXW2KMM.js +403 -0
- package/bin/chunks/tool-contract-ZWFZSYL4.js +32 -0
- package/bin/paper.js +258 -0
- package/dist/modes/interactive/theme/dark.json +85 -0
- package/dist/modes/interactive/theme/light.json +84 -0
- package/docs/cli.md +122 -0
- package/docs/paper-mcp.md +33 -0
- package/docs/runtime.md +54 -0
- package/package.json +79 -0
- package/tool-walk/fixtures.json +584 -0
- package/tool-walk/mono-safety-card.json +920 -0
- package/tool-walk/safety-fixtures.json +329 -0
- package/tools.contract.json +1748 -0
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "https://raw.githubusercontent.com/badlogic/pi-mono/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
|
|
3
|
+
"name": "dark",
|
|
4
|
+
"vars": {
|
|
5
|
+
"cyan": "#00d7ff",
|
|
6
|
+
"blue": "#5f87ff",
|
|
7
|
+
"green": "#b5bd68",
|
|
8
|
+
"red": "#cc6666",
|
|
9
|
+
"yellow": "#ffff00",
|
|
10
|
+
"gray": "#808080",
|
|
11
|
+
"dimGray": "#666666",
|
|
12
|
+
"darkGray": "#505050",
|
|
13
|
+
"accent": "#8abeb7",
|
|
14
|
+
"selectedBg": "#3a3a4a",
|
|
15
|
+
"userMsgBg": "#343541",
|
|
16
|
+
"toolPendingBg": "#282832",
|
|
17
|
+
"toolSuccessBg": "#283228",
|
|
18
|
+
"toolErrorBg": "#3c2828",
|
|
19
|
+
"customMsgBg": "#2d2838"
|
|
20
|
+
},
|
|
21
|
+
"colors": {
|
|
22
|
+
"accent": "accent",
|
|
23
|
+
"border": "blue",
|
|
24
|
+
"borderAccent": "cyan",
|
|
25
|
+
"borderMuted": "darkGray",
|
|
26
|
+
"success": "green",
|
|
27
|
+
"error": "red",
|
|
28
|
+
"warning": "yellow",
|
|
29
|
+
"muted": "gray",
|
|
30
|
+
"dim": "dimGray",
|
|
31
|
+
"text": "",
|
|
32
|
+
"thinkingText": "gray",
|
|
33
|
+
|
|
34
|
+
"selectedBg": "selectedBg",
|
|
35
|
+
"userMessageBg": "userMsgBg",
|
|
36
|
+
"userMessageText": "",
|
|
37
|
+
"customMessageBg": "customMsgBg",
|
|
38
|
+
"customMessageText": "",
|
|
39
|
+
"customMessageLabel": "#9575cd",
|
|
40
|
+
"toolPendingBg": "toolPendingBg",
|
|
41
|
+
"toolSuccessBg": "toolSuccessBg",
|
|
42
|
+
"toolErrorBg": "toolErrorBg",
|
|
43
|
+
"toolTitle": "",
|
|
44
|
+
"toolOutput": "gray",
|
|
45
|
+
|
|
46
|
+
"mdHeading": "#f0c674",
|
|
47
|
+
"mdLink": "#81a2be",
|
|
48
|
+
"mdLinkUrl": "dimGray",
|
|
49
|
+
"mdCode": "accent",
|
|
50
|
+
"mdCodeBlock": "green",
|
|
51
|
+
"mdCodeBlockBorder": "gray",
|
|
52
|
+
"mdQuote": "gray",
|
|
53
|
+
"mdQuoteBorder": "gray",
|
|
54
|
+
"mdHr": "gray",
|
|
55
|
+
"mdListBullet": "accent",
|
|
56
|
+
|
|
57
|
+
"toolDiffAdded": "green",
|
|
58
|
+
"toolDiffRemoved": "red",
|
|
59
|
+
"toolDiffContext": "gray",
|
|
60
|
+
|
|
61
|
+
"syntaxComment": "#6A9955",
|
|
62
|
+
"syntaxKeyword": "#569CD6",
|
|
63
|
+
"syntaxFunction": "#DCDCAA",
|
|
64
|
+
"syntaxVariable": "#9CDCFE",
|
|
65
|
+
"syntaxString": "#CE9178",
|
|
66
|
+
"syntaxNumber": "#B5CEA8",
|
|
67
|
+
"syntaxType": "#4EC9B0",
|
|
68
|
+
"syntaxOperator": "#D4D4D4",
|
|
69
|
+
"syntaxPunctuation": "#D4D4D4",
|
|
70
|
+
|
|
71
|
+
"thinkingOff": "darkGray",
|
|
72
|
+
"thinkingMinimal": "#6e6e6e",
|
|
73
|
+
"thinkingLow": "#5f87af",
|
|
74
|
+
"thinkingMedium": "#81a2be",
|
|
75
|
+
"thinkingHigh": "#b294bb",
|
|
76
|
+
"thinkingXhigh": "#d183e8",
|
|
77
|
+
|
|
78
|
+
"bashMode": "green"
|
|
79
|
+
},
|
|
80
|
+
"export": {
|
|
81
|
+
"pageBg": "#18181e",
|
|
82
|
+
"cardBg": "#1e1e24",
|
|
83
|
+
"infoBg": "#3c3728"
|
|
84
|
+
}
|
|
85
|
+
}
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "https://raw.githubusercontent.com/badlogic/pi-mono/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
|
|
3
|
+
"name": "light",
|
|
4
|
+
"vars": {
|
|
5
|
+
"teal": "#5a8080",
|
|
6
|
+
"blue": "#547da7",
|
|
7
|
+
"green": "#588458",
|
|
8
|
+
"red": "#aa5555",
|
|
9
|
+
"yellow": "#9a7326",
|
|
10
|
+
"mediumGray": "#6c6c6c",
|
|
11
|
+
"dimGray": "#767676",
|
|
12
|
+
"lightGray": "#b0b0b0",
|
|
13
|
+
"selectedBg": "#d0d0e0",
|
|
14
|
+
"userMsgBg": "#e8e8e8",
|
|
15
|
+
"toolPendingBg": "#e8e8f0",
|
|
16
|
+
"toolSuccessBg": "#e8f0e8",
|
|
17
|
+
"toolErrorBg": "#f0e8e8",
|
|
18
|
+
"customMsgBg": "#ede7f6"
|
|
19
|
+
},
|
|
20
|
+
"colors": {
|
|
21
|
+
"accent": "teal",
|
|
22
|
+
"border": "blue",
|
|
23
|
+
"borderAccent": "teal",
|
|
24
|
+
"borderMuted": "lightGray",
|
|
25
|
+
"success": "green",
|
|
26
|
+
"error": "red",
|
|
27
|
+
"warning": "yellow",
|
|
28
|
+
"muted": "mediumGray",
|
|
29
|
+
"dim": "dimGray",
|
|
30
|
+
"text": "",
|
|
31
|
+
"thinkingText": "mediumGray",
|
|
32
|
+
|
|
33
|
+
"selectedBg": "selectedBg",
|
|
34
|
+
"userMessageBg": "userMsgBg",
|
|
35
|
+
"userMessageText": "",
|
|
36
|
+
"customMessageBg": "customMsgBg",
|
|
37
|
+
"customMessageText": "",
|
|
38
|
+
"customMessageLabel": "#7e57c2",
|
|
39
|
+
"toolPendingBg": "toolPendingBg",
|
|
40
|
+
"toolSuccessBg": "toolSuccessBg",
|
|
41
|
+
"toolErrorBg": "toolErrorBg",
|
|
42
|
+
"toolTitle": "",
|
|
43
|
+
"toolOutput": "mediumGray",
|
|
44
|
+
|
|
45
|
+
"mdHeading": "yellow",
|
|
46
|
+
"mdLink": "blue",
|
|
47
|
+
"mdLinkUrl": "dimGray",
|
|
48
|
+
"mdCode": "teal",
|
|
49
|
+
"mdCodeBlock": "green",
|
|
50
|
+
"mdCodeBlockBorder": "mediumGray",
|
|
51
|
+
"mdQuote": "mediumGray",
|
|
52
|
+
"mdQuoteBorder": "mediumGray",
|
|
53
|
+
"mdHr": "mediumGray",
|
|
54
|
+
"mdListBullet": "green",
|
|
55
|
+
|
|
56
|
+
"toolDiffAdded": "green",
|
|
57
|
+
"toolDiffRemoved": "red",
|
|
58
|
+
"toolDiffContext": "mediumGray",
|
|
59
|
+
|
|
60
|
+
"syntaxComment": "#008000",
|
|
61
|
+
"syntaxKeyword": "#0000FF",
|
|
62
|
+
"syntaxFunction": "#795E26",
|
|
63
|
+
"syntaxVariable": "#001080",
|
|
64
|
+
"syntaxString": "#A31515",
|
|
65
|
+
"syntaxNumber": "#098658",
|
|
66
|
+
"syntaxType": "#267F99",
|
|
67
|
+
"syntaxOperator": "#000000",
|
|
68
|
+
"syntaxPunctuation": "#000000",
|
|
69
|
+
|
|
70
|
+
"thinkingOff": "lightGray",
|
|
71
|
+
"thinkingMinimal": "#767676",
|
|
72
|
+
"thinkingLow": "blue",
|
|
73
|
+
"thinkingMedium": "teal",
|
|
74
|
+
"thinkingHigh": "#875f87",
|
|
75
|
+
"thinkingXhigh": "#8b008b",
|
|
76
|
+
|
|
77
|
+
"bashMode": "green"
|
|
78
|
+
},
|
|
79
|
+
"export": {
|
|
80
|
+
"pageBg": "#f8f8f8",
|
|
81
|
+
"cardBg": "#ffffff",
|
|
82
|
+
"infoBg": "#fffae6"
|
|
83
|
+
}
|
|
84
|
+
}
|
package/docs/cli.md
ADDED
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
# CLI reference
|
|
2
|
+
|
|
3
|
+
## Requirements
|
|
4
|
+
|
|
5
|
+
- Node.js 22.19.0 or newer
|
|
6
|
+
- Paper Desktop with an open document for live reads and Paper workflows
|
|
7
|
+
- A supported model-provider login for `paper mono`
|
|
8
|
+
- User-installed `fd` (or `fdfind`) and `rg` on `PATH` for `paper mono`
|
|
9
|
+
|
|
10
|
+
Install the search tools before starting the specialist: `brew install fd ripgrep` on macOS, or `apt install fd-find ripgrep` on Debian or Ubuntu. Missing tools produce the same actionable failure in default and offline modes. Paper Mono never downloads executable dependencies automatically.
|
|
11
|
+
|
|
12
|
+
Install and confirm the public binary:
|
|
13
|
+
|
|
14
|
+
```bash
|
|
15
|
+
npm install -g paper-mono
|
|
16
|
+
paper --version
|
|
17
|
+
paper doctor --json
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
Both installed aliases use the same command contract. `paper` is canonical; `paper-mono` exists for package-name and `npx` workflows.
|
|
21
|
+
|
|
22
|
+
## Read commands
|
|
23
|
+
|
|
24
|
+
`paper show` and `paper info` report the active document. `paper selection` reports the current selection. `paper tree` resolves the active document root and returns its bounded tree summary.
|
|
25
|
+
|
|
26
|
+
Use `paper node <node-id>` for node information, `--children` for immediate children, or `--jsx` for Paper's JSX representation. `--children` and `--jsx` are mutually exclusive.
|
|
27
|
+
|
|
28
|
+
`paper screenshot --out <file>` resolves the current selection and requires exactly one selected node. Add `--node <node-id>` to target a node explicitly; an empty or multi-node selection exits with exact guidance before requesting an image. Paper must return exactly one image plus optional text with canonical base64 for PNG, JPEG, or WebP, and the declared MIME type must match the bytes' signature. If the path has no extension, the command appends the verified format. It refuses to overwrite an existing path. An extra image, malformed sibling part, noncanonical encoding, explicit extension mismatch, existing output, or any other payload failure exits without changing that path.
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
paper info --json
|
|
32
|
+
paper selection --json
|
|
33
|
+
paper tree --json
|
|
34
|
+
paper node "replace-with-node-id" --children --json
|
|
35
|
+
paper node "replace-with-node-id" --jsx --json
|
|
36
|
+
paper screenshot --out reference --node "replace-with-node-id" --json
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
Every deterministic command accepts `--json`. Read commands return `{ "result": <mcp-result> }`; screenshot returns `{ "out": <absolute-path>, "mimeType": <type> }`. JSON commands do not add decorative stdout.
|
|
40
|
+
|
|
41
|
+
## Diagnostics and identity
|
|
42
|
+
|
|
43
|
+
`paper doctor --json` checks the checked-in 27-tool contract against the live Paper MCP surface. Exit `0` means the diagnostic completed with zero `BROKEN` entries; it may still report `CRED-GATED` capabilities when Paper is closed or no document is open. Exit `1` means at least one entry is `BROKEN`. Automation that requires live readiness must inspect the structured `OK`, `CRED-GATED`, and `BROKEN` counts rather than treating exit `0` alone as readiness. Prerequisite guidance is emitted without a stack trace.
|
|
44
|
+
|
|
45
|
+
`paper --about-json` reports package identity, binary and agent-home paths, the tool-contract hash, registered and prompt tool IDs, mutation-lock metadata, and module provenance. Public installations report internal runtime modules as bundled.
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
paper --help
|
|
49
|
+
paper --about-json
|
|
50
|
+
paper doctor --json
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
## Specialist
|
|
54
|
+
|
|
55
|
+
`paper mono` starts the interactive design-to-code specialist. It supports persisted sessions, print/text/JSON modes, model selection, and the guarded reference-to-code, audit-only, and Paper-copilot workflows.
|
|
56
|
+
|
|
57
|
+
Run it from the destination repository root. The current working directory is recorded locally as the brief's project boundary, constrains approved edit/write paths, and is where approved commands launch. Generated model-request metadata renders that boundary as `<repository-root>` and labels context files relative to it instead of adding the absolute local project path. `@file` arguments accept only regular files contained by that repository after symlink resolution; attached contents become provider-bound prompt context under a repository-relative label. User-authored prompts, attached contents, imported instructions, tool results, and approved commands can still contain paths. Shell approval is an exact command-string gate, not an operating-system sandbox; review absolute paths, parent traversal, redirection, subprocesses, and package lifecycle scripts before approval.
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
paper mono --help
|
|
61
|
+
paper mono --audit-only
|
|
62
|
+
paper mono --copilot
|
|
63
|
+
paper mono --continue
|
|
64
|
+
paper mono --resume
|
|
65
|
+
paper mono --list-models
|
|
66
|
+
paper mono --audit-only --about-json
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
`paper mono --about-json` is a non-mutating argument and configuration metadata receipt; it does not initialize a runtime session. Combine it with `--audit-only`, `--copilot`, `--continue`, or `--resume` to inspect the selected workflow, requested session action, default lock contract, privacy defaults, and provenance without opening an interactive session.
|
|
70
|
+
|
|
71
|
+
Bare positional text after `paper mono` is prompt input, not a subcommand. Use `--` when prompt text itself begins with a hyphen: `paper mono -- --version` sends `--version` as prompt text rather than printing package metadata. The shorter `paper [options] [messages...]` form shares the specialist route only when it does not match an owner command. Its reserved owner words are `show`, `info`, `selection`, `tree`, `node`, `screenshot`, `doctor`, `page`, and `help`; use `paper mono` for unambiguous prompt text.
|
|
72
|
+
|
|
73
|
+
The public interactive runtime deliberately disables inherited `/debug`, `/export`, `/import`, and `/share` commands. They are absent from command autocomplete and are intercepted before upstream debug-log, file-writing, session-replacement, or network-sharing handlers can run. The global Shift+Ctrl+D debug shortcut is intercepted by the same boundary. Use the documented local session directory for your own backup process; Paper Mono does not provide a raw transcript debug, export, import, or share path in public v1.
|
|
74
|
+
|
|
75
|
+
The default agent home is `~/.paper/agent`. Override it with `PAPER_CODING_AGENT_DIR`. `--session <id>` accepts a verified session ID only; path-like values such as relative, absolute, symlink, or `.jsonl` paths are rejected before activation. Use `--fork <path-or-id>` for an explicit transcript import into a new session scoped to the current project. `--session-dir <dir>` overrides session storage and lookup only, may put transcripts outside the agent home, and uses the runtime's explicit-directory lookup instead of Paper Mono's hardened implicit-session verification path. Use only a trusted directory and include it separately in backup or removal plans. Set `PAPER_OFFLINE=1` or pass `--offline` to disable startup network operations; direct calls to Paper Desktop's local MCP server remain available.
|
|
76
|
+
|
|
77
|
+
## Exit and error behavior
|
|
78
|
+
|
|
79
|
+
- `0` means the requested command completed successfully.
|
|
80
|
+
- A nonzero exit means the command was invalid, a prerequisite was unavailable, a safety boundary refused the operation, or a live capability failed.
|
|
81
|
+
- For `paper doctor`, specifically, `0` means `BROKEN` is zero and can coexist with `CRED-GATED`; inspect the JSON summary to require live readiness.
|
|
82
|
+
- Machine-readable commands keep structured output on stdout. Human guidance and failure detail go to stderr.
|
|
83
|
+
- Unknown deterministic subcommands and unsupported specialist flags identify the rejected input and point back to `paper --help`. Invalid option values and conflicting `--continue` / `--resume` actions fail the same way.
|
|
84
|
+
- Interactive startup remains available for `/login`; headless or non-interactive model execution with a missing provider key exits nonzero with login/environment guidance and no runtime stack trace.
|
|
85
|
+
|
|
86
|
+
## Troubleshooting
|
|
87
|
+
|
|
88
|
+
### Paper closed or no file open
|
|
89
|
+
|
|
90
|
+
Open Paper Desktop and one document, then rerun `paper doctor --json`. The MCP bridge starts with the open document; reinstalling Paper Mono or restarting the CLI is not required.
|
|
91
|
+
|
|
92
|
+
### MCP endpoint unreachable
|
|
93
|
+
|
|
94
|
+
Paper Mono expects Paper's local MCP endpoint at `http://127.0.0.1:29979/mcp`. Confirm a document is open and rerun doctor. If the endpoint remains unavailable, close duplicate Paper processes and restart Paper Desktop before retrying.
|
|
95
|
+
|
|
96
|
+
### Missing model authentication
|
|
97
|
+
|
|
98
|
+
Start `paper mono`, enter `/login`, and choose a provider, or configure that provider's documented environment variable. Use `paper mono --list-models` to confirm the model ID. Do not paste keys into prompts, issue reports, or `paper doctor` output.
|
|
99
|
+
|
|
100
|
+
### Missing fd or rg
|
|
101
|
+
|
|
102
|
+
Install both search executables yourself and rerun the command: `brew install fd ripgrep` on macOS, or `apt install fd-find ripgrep` on Debian or Ubuntu. Paper Mono refuses specialist startup rather than downloading an unpinned executable. `--offline` follows the same fail-closed behavior.
|
|
103
|
+
|
|
104
|
+
### Oversized Snapshot or result budget
|
|
105
|
+
|
|
106
|
+
Confirm identity with `paper info --json`, select one artboard, and inspect a bounded tree before requesting rich output. Ask the specialist for a scale-1 screenshot and JSX/styles for one subtree. If Paper Mono returns an over-budget receipt, follow its narrower retry guidance; rich JSON, JSX, and base64 are suppressed whole rather than truncated.
|
|
107
|
+
|
|
108
|
+
### Wrong file, page, artboard, or node
|
|
109
|
+
|
|
110
|
+
Run `paper info --json` and `paper selection --json`, switch to the intended target in Paper, and request a new brief. A changed target invalidates prior approval. Do not approve a brief whose file, page, artboard, or node identities differ from the intended reference.
|
|
111
|
+
|
|
112
|
+
### Malformed or unsupported imported structure
|
|
113
|
+
|
|
114
|
+
Try a smaller semantic node, a targeted screenshot, or a different imported artboard. The brief should mark hidden, unavailable, or unsupported details as unknown. Do not treat a generic reconstruction as evidence that the source was understood.
|
|
115
|
+
|
|
116
|
+
### Resume is locked again
|
|
117
|
+
|
|
118
|
+
This is expected. Resuming never carries mutation authority forward. Inspect the current target, receive the current brief, and enter its newly issued exact approval phrase only if the scope is still correct.
|
|
119
|
+
|
|
120
|
+
### Binary or version mismatch
|
|
121
|
+
|
|
122
|
+
Run `paper --version`, `paper-mono --version`, and your shell's command-location utility. Both aliases must report the same installed version. If they do not, uninstall stale global copies, reinstall `paper-mono`, and rerun doctor.
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
# Paper MCP boundary
|
|
2
|
+
|
|
3
|
+
Paper Desktop exposes a local MCP server at `http://127.0.0.1:29979/mcp` while a document is open. Paper Mono translates its checked-in 27-tool contract into bounded reads, dry runs, and guarded Paper operations. It does not expose the raw provider surface.
|
|
4
|
+
|
|
5
|
+
Every file-scoped call carries an explicit Paper file identity. Reference inspection starts with basic document information, then narrows through selection, tree, search, node, screenshot, JSX, and computed-style reads.
|
|
6
|
+
|
|
7
|
+
## Bounded inspection
|
|
8
|
+
|
|
9
|
+
- Tree depth defaults to 4 and accepts only 1 through 8.
|
|
10
|
+
- Computed-style reads accept 1 through 50 node IDs.
|
|
11
|
+
- Rich text results are limited to 163,840 UTF-8 bytes.
|
|
12
|
+
- Decoded image results are limited to 6,291,456 bytes.
|
|
13
|
+
- An over-budget content part is suppressed whole. Paper Mono never returns partial JSON, JSX, or base64.
|
|
14
|
+
- Retry receipts point to a smaller subtree, shallower depth, fewer node IDs, or a targeted scale-1 screenshot.
|
|
15
|
+
|
|
16
|
+
These limits keep a full-page Snapshot from silently flooding or corrupting the model context while preserving normal-sized MCP responses.
|
|
17
|
+
|
|
18
|
+
## Paper Snapshot
|
|
19
|
+
|
|
20
|
+
Paper Snapshot is Paper's separate Chrome extension. [Get it from Paper's official page](https://paper.design/snapshot-extension) to import a web reference into Paper; Paper Mono only reads the resulting Paper document. It does not operate Chrome, run the extension, or claim that an imported screenshot proves the destination product.
|
|
21
|
+
|
|
22
|
+
For a large or awkward Snapshot:
|
|
23
|
+
|
|
24
|
+
1. confirm the active file with `paper info --json`;
|
|
25
|
+
2. confirm the selection with `paper selection --json`;
|
|
26
|
+
3. use `paper tree --json` or targeted node search instead of requesting the entire root;
|
|
27
|
+
4. capture one relevant node or artboard at scale 1;
|
|
28
|
+
5. request JSX or styles only for the subtree needed for the current decision;
|
|
29
|
+
6. summarize structure, hierarchy, typography, spacing, color, assets, and interaction implications before reading another subtree;
|
|
30
|
+
7. mark hidden, malformed, unavailable, or unsupported structure as uncertainty rather than inventing it;
|
|
31
|
+
8. adapt the direction through the destination's own design system and verify that product independently.
|
|
32
|
+
|
|
33
|
+
The machine-readable surface is included as `tools.contract.json`. `paper doctor --json` checks that contract against the live Paper MCP bridge and reports every required capability as available, credential-gated, or broken. Exit `0` means there are zero broken entries, not necessarily that every capability is live; readiness automation must inspect the structured summary for credential-gated entries.
|
package/docs/runtime.md
ADDED
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
# Runtime, privacy, and compatibility
|
|
2
|
+
|
|
3
|
+
Paper Mono is a local CLI. It has no required Paper Mono account, hosted backend, Convex deployment, browser automation service, or telemetry service. Paper Desktop remains the design-file authority.
|
|
4
|
+
|
|
5
|
+
## Approval model
|
|
6
|
+
|
|
7
|
+
The default reference-to-code workflow is:
|
|
8
|
+
|
|
9
|
+
1. inspect the Paper reference and destination project without mutation;
|
|
10
|
+
2. produce a `paper-implementation-brief.v1` bound to the observed Paper target and proposed project scope;
|
|
11
|
+
3. wait for the exact standalone `APPROVE PAPER BRIEF <brief-id>` phrase;
|
|
12
|
+
4. unlock only the tools, Paper targets, project paths, and shell commands named by that brief;
|
|
13
|
+
5. relock after the run, target drift, ordinary user input, session navigation, reload, fork, or resume;
|
|
14
|
+
6. verify the implemented product in its real route, viewport, state, and interaction loop.
|
|
15
|
+
|
|
16
|
+
`--audit-only` can never unlock mutation. `--copilot` uses the same approval boundary for guarded work inside Paper. Dry-run-capable Paper mutations remain dry runs until the approved live call is made.
|
|
17
|
+
|
|
18
|
+
The approval gate is runtime enforcement, not a prompt convention: unapproved project writes, shell commands, live Paper mutations, external tools, and direct page-control routes are blocked before their implementation runs. Edit and write tools enforce approved project paths. An approved shell command must exactly match the brief and launches from the project directory, but it runs in the normal host shell—not an operating-system sandbox. Absolute paths, parent traversal, redirection, subprocesses, and package lifecycle scripts can still affect paths outside the project, so review every proposed command before approval. The explicit pre-approval exception is the separate deterministic `paper screenshot --out <file>` command: it creates only the requested image path, appends a verified extension when needed, and refuses to overwrite an existing file. The package includes `SAFETY.md`, `tools.contract.json`, and `tool-walk/mono-safety-card.json` as human- and machine-readable evidence of that boundary.
|
|
19
|
+
|
|
20
|
+
## Local and remote data flow
|
|
21
|
+
|
|
22
|
+
- Paper reads use Paper Desktop's loopback MCP server at `127.0.0.1`; Paper Mono does not upload a document to its own backend.
|
|
23
|
+
- Credentials, settings, and sessions live under `~/.paper/agent` by default. `PAPER_CODING_AGENT_DIR` selects another local directory. `--session <id>` accepts a verified session ID only; path-like values are rejected before activation. `--fork <path-or-id>` explicitly imports a transcript into a new session scoped to the current project. `--session-dir <dir>` overrides session storage and lookup, may place transcripts outside the agent home, and uses the runtime's explicit-directory lookup instead of Paper Mono's hardened implicit-session verification path. Use only a trusted directory; package uninstall does not remove it.
|
|
24
|
+
- Explicit `@file` inputs are limited to regular files contained by the destination repository after symlink resolution. Their contents, or processed image data, are added to the prompt context sent to the selected model provider under repository-relative labels. Generated system, context, and approval metadata renders the local project as `<repository-root>` instead of adding its absolute path. User-authored prompts, attached contents, imported instructions, tool results, or approved commands can still contain paths.
|
|
25
|
+
- Prompts, relevant project/reference context, and tool results needed for reasoning are sent to the model provider selected by the user. That provider's privacy, retention, and billing terms apply.
|
|
26
|
+
- Paper Mono does not print credential values in diagnostics. It forces inherited install telemetry, automatic version polling, and provider-attribution telemetry off before specialist startup, and adds no product telemetry or silent phone-home service.
|
|
27
|
+
- Inherited `/debug`, `/export`, `/import`, and `/share` TUI commands are removed from autocomplete and intercepted before dispatch. The global Shift+Ctrl+D debug shortcut is intercepted as well. A public Paper Mono session cannot use those paths to write or replace a transcript or upload it to Radius or GitHub Gist.
|
|
28
|
+
- Specialist startup requires user-installed `fd` (or `fdfind`) and `rg` on `PATH`. Paper Mono checks them before creating the specialist session and keeps the inherited unpinned executable downloader disabled for the rest of the process. Default and explicit-offline launches fail with the same install guidance when either tool is missing.
|
|
29
|
+
- `PAPER_OFFLINE=1` or `--offline` disables startup network operations. It does not make a remote model provider local; use a configured local provider or deterministic Paper commands when a network-free workflow is required.
|
|
30
|
+
|
|
31
|
+
## Authentication
|
|
32
|
+
|
|
33
|
+
Run `paper mono`, enter `/login`, and choose a supported provider. Provider environment variables are also accepted where supported by the runtime. `paper mono --list-models` displays available model IDs. Interactive startup remains available so you can enter `/login`; headless or non-interactive model execution without credentials exits nonzero with guided instructions instead of a stack trace.
|
|
34
|
+
|
|
35
|
+
Never share `~/.paper/agent/auth.json`, provider keys, or unredacted session transcripts in support reports.
|
|
36
|
+
|
|
37
|
+
## Compatibility
|
|
38
|
+
|
|
39
|
+
- Required runtime: Node.js 22.19.0 or newer.
|
|
40
|
+
- Required search tools: user-installed `fd` (or `fdfind`) and `rg` on `PATH`; Paper Mono never acquires executable dependencies.
|
|
41
|
+
- Required design app: Paper Desktop with a document open for live MCP work.
|
|
42
|
+
- Clean-room proof environment: Apple-silicon macOS with Node.js 22.23.1 for installation, offline CLI behavior, both aliases, `npx`, documentation probes, dependency audit, and uninstall.
|
|
43
|
+
- The clean-room resume gate drives the real installed `-r` and `--resume` picker against two named sessions in the default implicit session store, proves the selected session identity and locked tool inventory, bounds its append-only startup records, and verifies that cancellation leaves both session files byte-identical. That hardened implicit-session proof does not cover the explicit `--session-dir` override.
|
|
44
|
+
- That clean-room receipt explicitly does not claim live Paper Desktop integration. The package intentionally has no restrictive `os` field, but Linux and Windows live integration remain unproven until the complete Paper-open workflow is exercised there.
|
|
45
|
+
- The local MCP service currently uses `http://127.0.0.1:29979/mcp`.
|
|
46
|
+
|
|
47
|
+
## Known limitations
|
|
48
|
+
|
|
49
|
+
- Paper Snapshot is an external Chrome extension; Paper Mono cannot trigger or control it.
|
|
50
|
+
- A static reference cannot prove source motion, hidden states, server behavior, or assets Paper did not import. Briefs must label those as unknown.
|
|
51
|
+
- Full-page Snapshots require bounded, progressive inspection. Root-scale rich reads can be suppressed by the runtime budget.
|
|
52
|
+
- Paper's provider surface does not expose every page-management or design operation. Raw provider calls are intentionally not available as a bypass.
|
|
53
|
+
- A Paper screenshot is reference evidence, not proof that the destination implementation is correct. Product verification happens in the destination route and interaction state.
|
|
54
|
+
- Public source and a public issue tracker are deferred until the npm product stabilizes. Support and security reports currently use the public contact in `README.md` and `SAFETY.md`.
|
package/package.json
ADDED
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "paper-mono",
|
|
3
|
+
"version": "0.62.0",
|
|
4
|
+
"description": "Local-first Paper Desktop design-to-code specialist for agents and humans",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"license": "MIT",
|
|
7
|
+
"author": "Luke Nittmann",
|
|
8
|
+
"bin": {
|
|
9
|
+
"paper": "bin/paper.js",
|
|
10
|
+
"paper-mono": "bin/paper.js"
|
|
11
|
+
},
|
|
12
|
+
"files": [
|
|
13
|
+
"bin",
|
|
14
|
+
"dist",
|
|
15
|
+
"docs",
|
|
16
|
+
"tool-walk",
|
|
17
|
+
"CHANGELOG.md",
|
|
18
|
+
"DEPENDENCIES.json",
|
|
19
|
+
"LICENSE",
|
|
20
|
+
"README.md",
|
|
21
|
+
"SAFETY.md",
|
|
22
|
+
"THIRD_PARTY_NOTICES.md",
|
|
23
|
+
"tools.contract.json"
|
|
24
|
+
],
|
|
25
|
+
"dependencies": {
|
|
26
|
+
"@earendil-works/pi-agent-core": "0.84.3",
|
|
27
|
+
"@earendil-works/pi-ai": "0.84.3",
|
|
28
|
+
"@earendil-works/pi-coding-agent": "0.84.3",
|
|
29
|
+
"@earendil-works/pi-tui": "0.84.3",
|
|
30
|
+
"@silvia-odwyer/photon-node": "0.3.4",
|
|
31
|
+
"@sinclair/typebox": "0.34.48",
|
|
32
|
+
"chalk": "5.6.2",
|
|
33
|
+
"cli-highlight": "2.1.11",
|
|
34
|
+
"debug": "4.4.3",
|
|
35
|
+
"undici": "7.29.0",
|
|
36
|
+
"yaml": "2.9.0",
|
|
37
|
+
"yauzl": "3.4.0"
|
|
38
|
+
},
|
|
39
|
+
"engines": {
|
|
40
|
+
"node": ">=22.19.0"
|
|
41
|
+
},
|
|
42
|
+
"keywords": [
|
|
43
|
+
"paper",
|
|
44
|
+
"design-to-code",
|
|
45
|
+
"coding-agent",
|
|
46
|
+
"mcp",
|
|
47
|
+
"cli"
|
|
48
|
+
],
|
|
49
|
+
"publishConfig": {
|
|
50
|
+
"access": "public"
|
|
51
|
+
},
|
|
52
|
+
"piConfig": {
|
|
53
|
+
"name": "paper",
|
|
54
|
+
"configDir": ".paper"
|
|
55
|
+
},
|
|
56
|
+
"paperMono": {
|
|
57
|
+
"distribution": "public-bundle",
|
|
58
|
+
"bundledPackages": {
|
|
59
|
+
"@creative-int/mono": "0.21.0",
|
|
60
|
+
"@creative-int/pi-coding-core": "0.7.0",
|
|
61
|
+
"@creative-int/pi-coding-runtime": "0.7.0",
|
|
62
|
+
"@creative-int/pi-prompts": "0.4.2"
|
|
63
|
+
},
|
|
64
|
+
"runtimeAssets": [
|
|
65
|
+
{
|
|
66
|
+
"path": "dist/modes/interactive/theme/dark.json",
|
|
67
|
+
"sourcePackage": "@creative-int/pi-coding-core",
|
|
68
|
+
"sourcePath": "dist/modes/interactive/theme/dark.json",
|
|
69
|
+
"sha256": "1d809f2794166584bf4fd8bea0c547f2c75483013fe367e00ccde961ec403c7d"
|
|
70
|
+
},
|
|
71
|
+
{
|
|
72
|
+
"path": "dist/modes/interactive/theme/light.json",
|
|
73
|
+
"sourcePackage": "@creative-int/pi-coding-core",
|
|
74
|
+
"sourcePath": "dist/modes/interactive/theme/light.json",
|
|
75
|
+
"sha256": "1d6b3ce3f89b5ccd0de423a0c7ef97a58df193a60ffd6592a3f414d559aabbdb"
|
|
76
|
+
}
|
|
77
|
+
]
|
|
78
|
+
}
|
|
79
|
+
}
|