paragma 0.2.7 → 0.3.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 +20 -2
- package/SHA256SUMS +6 -6
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -26,6 +26,8 @@ pg setup
|
|
|
26
26
|
|
|
27
27
|
That is all. `npm` fetches the build of `pg` for your computer (Windows, macOS or Linux, on x64 or arm64) and checks it against the release's SHA-256 sums. It needs Node 18 or later. `pg setup` then opens a small screen where you pick your coding agents and where Paragma should be read: in every conversation, or only in one project's folder.
|
|
28
28
|
|
|
29
|
+
A newer npm may warn that `paragma` has install scripts not covered by `allowScripts`. That is fine: the first `pg` call fetches the binary instead.
|
|
30
|
+
|
|
29
31
|
<details>
|
|
30
32
|
<summary>Without npm</summary>
|
|
31
33
|
|
|
@@ -33,7 +35,7 @@ Download `pg` for your platform from the [releases](https://github.com/Utku4836/
|
|
|
33
35
|
|
|
34
36
|
</details>
|
|
35
37
|
|
|
36
|
-
Your memory lives in `~/.paragma`, outside your repositories. Paragma
|
|
38
|
+
Your memory lives in `~/.paragma`, outside your repositories. Paragma works offline; the search model is built into `pg`. Only `pg git`, once you connect it, talks to GitHub.
|
|
37
39
|
|
|
38
40
|
## Why
|
|
39
41
|
|
|
@@ -140,6 +142,8 @@ pg write --decision "..." --why "..." --alternatives "..."
|
|
|
140
142
|
pg write --error "<error line>" --cause "..." --fix "..."
|
|
141
143
|
pg write payments/provider --file notes.md # a note; long text from a file or stdin (-)
|
|
142
144
|
pg finish --done 1 "what changed, what is next" # tick off steps, leave the handoff
|
|
145
|
+
pg steps # the steps with their numbers (--drop 4, --edit 4 "text")
|
|
146
|
+
pg ripple # what a change reaches: callers left as they were, tests to run
|
|
143
147
|
pg tree # the code: files and symbols, with the notes about them marked
|
|
144
148
|
pg ls # projects, or the notes of one; also pg mv, pg rm, pg doctor
|
|
145
149
|
```
|
|
@@ -157,13 +161,27 @@ pg run -- npm publish --token '$NPM_PUBLISH_TOKEN'
|
|
|
157
161
|
|
|
158
162
|
`pg run` puts the value in place itself, on every platform, and prints `$NPM_PUBLISH_TOKEN` again wherever the value would appear in the output. Keys pasted into notes are masked and not kept. In a test with 50 keys and ten requests in plain words, the right key came first every time and was used through `pg run` without its value appearing in any output.
|
|
159
163
|
|
|
164
|
+
### Backup and sync
|
|
165
|
+
|
|
166
|
+
```bash
|
|
167
|
+
pg git
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
Opens a small screen: sign in to GitHub (with the GitHub CLI or the sign-in git already has, else in the browser with a code), then choose where the memory goes: a new private repository (`paragma-memory`, of your account or of one of its organizations), or one you have, in a `Paragma/` folder on its own branch or on its main branch. Choosing a public repository asks first. The `.env` files go only if you say so, and never to a public repository.
|
|
171
|
+
|
|
172
|
+
From then on every change goes there by itself, a few seconds after it is made, in the background: the agent never waits for it. What other computers sent comes in the same way. On a new computer, `pg git` finds the memory in your repositories (your own and your organizations') and restores it, joined with whatever is already there. The indexes and the short-lived state in `.pg/` never go; they are rebuilt.
|
|
173
|
+
|
|
174
|
+
Run `pg git` again to see the account, the repository and the last sync, to change the `.env` setting, to move the memory to another repository (other computers follow by themselves) or to disconnect. Without a terminal: `pg git connect --new`, `pg git status`, `pg git sync`, `pg git env on|off`, `pg git move --repo owner/name`, `pg git disconnect`.
|
|
175
|
+
|
|
160
176
|
## How it works
|
|
161
177
|
|
|
162
178
|
- **Plain Markdown.** Each project is a folder in `~/.paragma/projects/`: `project.md` (goal, steps, handoffs), `rules.md`, `decisions/`, `errors/` and any notes you like. Open it in any editor; edits are picked up on the next call.
|
|
163
179
|
- **Hybrid search.** Full-text search (SQLite FTS5) and meaning search with a multilingual embedding model built into the binary ([potion-multilingual-128M](https://huggingface.co/minishlab/potion-multilingual-128M), reduced to Latin scripts and 4-bit), merged by rank. A question in Turkish finds a note written in English.
|
|
164
180
|
- **Code awareness.** Paragma reads 20 programming languages, the shading languages (WGSL, GLSL, HLSL), SQL, GraphQL, Protobuf, Dockerfiles, CI and compose files, Vue and Svelte: files, functions, types, what each function calls. Shaders and queries kept in strings (``/* wgsl */ `...` ``, ``sql`...` ``) are read as their language, and Markdown documents by their sections, so the brief and `pg find` name the section to read. Notes are linked to code by path and symbol, and record the state of the code when they were written, so a note says when it may be out of date.
|
|
181
|
+
- **What a change reaches.** `pg ripple` compares the code with the last commit: a function whose signature changed, renamed or removed, with the callers the change left as they were and the tests that reach it; a shader struct, GraphQL or Protobuf type or SQL table whose fields changed, with the other code that names them. `pg run`, the hooks and `pg finish` say it by themselves; `pg ripple Refund` tells what reaches a function before changing it.
|
|
182
|
+
- **Libraries at their versions.** The libraries a project locks (Cargo.lock, node_modules, go.mod, a virtual environment) are read from the source already on the computer, when an agent asks: `pg find "serde_json Value get"` gives the real signature, doc, example, the feature it needs and deprecation at that version; a failed build that looked for a name a library does not have gets the right one from `pg run`; an upgrade is pointed out in the brief with what changed in what the code calls.
|
|
165
183
|
- **Records that merge.** Writing a rule, decision or error that is already known updates the existing one instead of adding a copy; a decision that contradicts an earlier one is pointed out.
|
|
166
|
-
- **One binary.** `pg` is written in Rust: no runtime, no server, no network. The indexes next to the notes can be deleted at any time and are rebuilt.
|
|
184
|
+
- **One binary.** `pg` is written in Rust: no runtime, no server, and no network unless you connect `pg git` (it uses git and curl). The indexes next to the notes can be deleted at any time and are rebuilt.
|
|
167
185
|
|
|
168
186
|
## How it is tested
|
|
169
187
|
|
package/SHA256SUMS
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
1
|
+
6579a0c8dc1eb5230c554f8172c15d32df4c40a6abe7456f1de867cda47f9615 pg-darwin-arm64
|
|
2
|
+
6a35f09f8ccab9425e255b46166e57f4d3e10f8334d510ef78167f6054de9ca9 pg-darwin-x64
|
|
3
|
+
ecbb038504922ae7b1b0890faeedaf59e150906f1a797b560f792bbcfbd9b311 pg-linux-arm64
|
|
4
|
+
506e76072ccb6bb1917aea6a2fca9a9653062e718040dc0a739c1e1fcbb37c64 pg-linux-x64
|
|
5
|
+
a5ed42cc2708f62ea067aadf05eca04035cc32df1849d3d2e89a1bca53b388e6 pg-windows-arm64.exe
|
|
6
|
+
e28cc72aea793b6b87063c36eb352882f0147323705ba19052f3910f9c42f5e8 pg-windows-x64.exe
|
package/package.json
CHANGED