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.
Files changed (3) hide show
  1. package/README.md +20 -2
  2. package/SHA256SUMS +6 -6
  3. 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 never opens a network connection; the search model is built into `pg`.
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
- 3925ee7b9390989cb702528ca99a89f3dbb0ba74f9b203de885c6e03d81fefd9 pg-darwin-arm64
2
- 99836619bfbaa7314f7b4d7b13f4756c5e2456c007d7cfb022d96efc5340098f pg-darwin-x64
3
- abce83da17188c8789aebefda7e4f32de5940967d6399bb19eae026b5cd18b3f pg-linux-arm64
4
- 968d0da083075cf223f0fbdb04e5134d680af99c3724bc4e6aad13e6c6eff24e pg-linux-x64
5
- 5c5a13308acdddafaaeafd4ea1d3009f51b4478af6381b79883177e81edd0b33 pg-windows-arm64.exe
6
- 32f85609f703f83a3ab6aa0686e73fc2339d6204d7cf89907c2302730fb0bb30 pg-windows-x64.exe
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "paragma",
3
- "version": "0.2.7",
3
+ "version": "0.3.1",
4
4
  "description": "Project memory for AI coding agents: rules, decisions, past errors with their fixes, and handoffs between conversations, found by hybrid search.",
5
5
  "keywords": [
6
6
  "ai",