paragma 0.2.6 → 0.3.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/README.md +19 -2
- package/SHA256SUMS +6 -6
- package/bin/pg +8 -1
- package/install.js +116 -10
- 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,7 @@ 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 ripple # what a change reaches: callers left as they were, tests to run
|
|
143
146
|
pg tree # the code: files and symbols, with the notes about them marked
|
|
144
147
|
pg ls # projects, or the notes of one; also pg mv, pg rm, pg doctor
|
|
145
148
|
```
|
|
@@ -157,13 +160,27 @@ pg run -- npm publish --token '$NPM_PUBLISH_TOKEN'
|
|
|
157
160
|
|
|
158
161
|
`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
162
|
|
|
163
|
+
### Backup and sync
|
|
164
|
+
|
|
165
|
+
```bash
|
|
166
|
+
pg git
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
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`), 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.
|
|
170
|
+
|
|
171
|
+
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.
|
|
172
|
+
|
|
173
|
+
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`.
|
|
174
|
+
|
|
160
175
|
## How it works
|
|
161
176
|
|
|
162
177
|
- **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
178
|
- **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
179
|
- **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.
|
|
180
|
+
- **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.
|
|
181
|
+
- **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
182
|
- **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.
|
|
183
|
+
- **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
184
|
|
|
168
185
|
## How it is tested
|
|
169
186
|
|
package/SHA256SUMS
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
1
|
+
5fb0e7851a5b463d64c949ae9e940927eb86dd35c5466bbb4a73af20d471a140 pg-darwin-arm64
|
|
2
|
+
d20bf0257481faa4385235bc53fc5669a1945de8342adf0b34ce1fc0c1c06a6f pg-darwin-x64
|
|
3
|
+
a73eb5cca079271642fdbaa4c90594ed5857cc0a05a650b7b1b568007b451042 pg-linux-arm64
|
|
4
|
+
950eecf79c46163635bec0436efa551c242380b8ae23939c7f09362ced4c431f pg-linux-x64
|
|
5
|
+
2a523e3622166699e657e0f0597265569325a634e65ca28ccb00cc427300bd5e pg-windows-arm64.exe
|
|
6
|
+
8682f8501c0d8d9098daa6574d979c7392201028ccc0c48293c15a52a0dc8bfd pg-windows-x64.exe
|
package/bin/pg
CHANGED
|
@@ -1,10 +1,12 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
// Runs the native pg binary for this computer, downloading it first when
|
|
3
3
|
// the install did not (install scripts turned off, or no network then).
|
|
4
|
+
// On Windows the first call also points npm's shims at the binary, so the
|
|
5
|
+
// calls after it do not go through Node (see install.js, direct).
|
|
4
6
|
"use strict";
|
|
5
7
|
const { spawnSync } = require("child_process");
|
|
6
8
|
const fs = require("fs");
|
|
7
|
-
const { install, binaryPath } = require("../install.js");
|
|
9
|
+
const { install, binaryPath, direct } = require("../install.js");
|
|
8
10
|
|
|
9
11
|
async function main() {
|
|
10
12
|
let exe = binaryPath();
|
|
@@ -22,6 +24,11 @@ async function main() {
|
|
|
22
24
|
process.exit(7);
|
|
23
25
|
}
|
|
24
26
|
}
|
|
27
|
+
try {
|
|
28
|
+
direct(exe);
|
|
29
|
+
} catch {
|
|
30
|
+
// the shims stay as npm wrote them: pg still works, through Node
|
|
31
|
+
}
|
|
25
32
|
const r = spawnSync(exe, process.argv.slice(2), { stdio: "inherit" });
|
|
26
33
|
if (r.error) {
|
|
27
34
|
console.error("paragma: " + r.error.message);
|
package/install.js
CHANGED
|
@@ -3,12 +3,12 @@
|
|
|
3
3
|
// package's version and checks it against SHA256SUMS (packed into the
|
|
4
4
|
// package when it was published). Runs after `npm install`; when install
|
|
5
5
|
// scripts are turned off, bin/pg runs it on the first call instead.
|
|
6
|
+
//
|
|
7
|
+
// On Windows it then points npm's pg, pg.cmd and pg.ps1 straight at the
|
|
8
|
+
// binary: through Node every call took about half a second more.
|
|
6
9
|
"use strict";
|
|
7
|
-
const crypto = require("crypto");
|
|
8
10
|
const fs = require("fs");
|
|
9
|
-
const https = require("https");
|
|
10
11
|
const path = require("path");
|
|
11
|
-
const zlib = require("zlib");
|
|
12
12
|
|
|
13
13
|
const REPO = "Utku4836/Paragma";
|
|
14
14
|
const OS = { win32: "windows", linux: "linux", darwin: "darwin" };
|
|
@@ -39,6 +39,7 @@ function expectedSum(name) {
|
|
|
39
39
|
}
|
|
40
40
|
|
|
41
41
|
function get(url, redirects = 5) {
|
|
42
|
+
const https = require("https");
|
|
42
43
|
return new Promise((resolve, reject) => {
|
|
43
44
|
https
|
|
44
45
|
.get(url, { headers: { "User-Agent": "paragma-installer" } }, (res) => {
|
|
@@ -67,9 +68,9 @@ async function install({ quiet = false } = {}) {
|
|
|
67
68
|
if (!quiet) process.stderr.write(`paragma: downloading pg ${version} for ${process.platform}/${process.arch}...\n`);
|
|
68
69
|
const res = await get(url);
|
|
69
70
|
const tmp = `${dest}.${process.pid}.tmp`;
|
|
70
|
-
const hash = crypto.createHash("sha256");
|
|
71
|
+
const hash = require("crypto").createHash("sha256");
|
|
71
72
|
await new Promise((resolve, reject) => {
|
|
72
|
-
const gunzip = zlib.createGunzip();
|
|
73
|
+
const gunzip = require("zlib").createGunzip();
|
|
73
74
|
const out = fs.createWriteStream(tmp, { mode: 0o755 });
|
|
74
75
|
gunzip.on("data", (chunk) => hash.update(chunk));
|
|
75
76
|
res.on("error", reject);
|
|
@@ -90,11 +91,116 @@ async function install({ quiet = false } = {}) {
|
|
|
90
91
|
return dest;
|
|
91
92
|
}
|
|
92
93
|
|
|
93
|
-
|
|
94
|
+
const MARK = "written by paragma (install.js): runs pg itself, not through Node";
|
|
95
|
+
|
|
96
|
+
/**
|
|
97
|
+
* npm's shims for pg that run it through Node, with what each becomes:
|
|
98
|
+
* pg (Git Bash and other sh), pg.cmd and pg.ps1, in the folder of a global
|
|
99
|
+
* install (<prefix>, the package in <prefix>/node_modules/paragma) or of a
|
|
100
|
+
* local one (node_modules/.bin). A shim is known by the launcher path npm
|
|
101
|
+
* wrote in it; the new one is written as npm writes them and points inside
|
|
102
|
+
* the package too, so npm still treats it as its own: an update writes it
|
|
103
|
+
* anew (the first call then points it again), an uninstall removes it.
|
|
104
|
+
*/
|
|
105
|
+
function shims(exe) {
|
|
106
|
+
const launcher = path.join(__dirname, "bin", "pg");
|
|
107
|
+
const dirs = [path.resolve(__dirname, "..", ".."), path.resolve(__dirname, "..", ".bin")];
|
|
108
|
+
const found = [];
|
|
109
|
+
for (const dir of dirs) {
|
|
110
|
+
const slash = (p) => path.relative(dir, p).split(path.sep).join("/");
|
|
111
|
+
const back = (p) => path.relative(dir, p).split(path.sep).join("\\");
|
|
112
|
+
const sh = [
|
|
113
|
+
"#!/bin/sh",
|
|
114
|
+
`# ${MARK}`,
|
|
115
|
+
'case "$0" in',
|
|
116
|
+
` *\\\\*) basedir=$(dirname "$(echo "$0" | sed -e 's,\\\\,/,g')") ;;`,
|
|
117
|
+
" */*) basedir=${0%/*} ;;",
|
|
118
|
+
" *) basedir=. ;;",
|
|
119
|
+
"esac",
|
|
120
|
+
`if [ -f "$basedir/${slash(exe)}" ]; then`,
|
|
121
|
+
` exec "$basedir/${slash(exe)}" "$@"`,
|
|
122
|
+
"fi",
|
|
123
|
+
"# the binary is gone (an update): Node's launcher downloads it again",
|
|
124
|
+
`exec node "$basedir/${slash(launcher)}" "$@"`,
|
|
125
|
+
"",
|
|
126
|
+
].join("\n");
|
|
127
|
+
const cmd = [
|
|
128
|
+
"@ECHO off",
|
|
129
|
+
`REM ${MARK}`,
|
|
130
|
+
"GOTO start",
|
|
131
|
+
":find_dp0",
|
|
132
|
+
"SET dp0=%~dp0",
|
|
133
|
+
"EXIT /b",
|
|
134
|
+
":start",
|
|
135
|
+
"SETLOCAL",
|
|
136
|
+
"CALL :find_dp0",
|
|
137
|
+
`IF NOT EXIST "%dp0%\\${back(exe)}" GOTO node`,
|
|
138
|
+
`endLocal & goto #_undefined_# 2>NUL || title %COMSPEC% & "%dp0%\\${back(exe)}" %*`,
|
|
139
|
+
":node",
|
|
140
|
+
"REM the binary is gone (an update): Node's launcher downloads it again",
|
|
141
|
+
`endLocal & goto #_undefined_# 2>NUL || title %COMSPEC% & "node" "%dp0%\\${back(launcher)}" %*`,
|
|
142
|
+
"",
|
|
143
|
+
].join("\r\n");
|
|
144
|
+
const ps1 = [
|
|
145
|
+
"#!/usr/bin/env pwsh",
|
|
146
|
+
`# ${MARK}`,
|
|
147
|
+
"$basedir=Split-Path $MyInvocation.MyCommand.Definition -Parent",
|
|
148
|
+
`if (-not (Test-Path "$basedir/${slash(exe)}")) {`,
|
|
149
|
+
" # the binary is gone (an update): Node's launcher downloads it again",
|
|
150
|
+
` & node "$basedir/${slash(launcher)}" $args`,
|
|
151
|
+
" exit $LASTEXITCODE",
|
|
152
|
+
"}",
|
|
153
|
+
"if ($MyInvocation.ExpectingInput) {",
|
|
154
|
+
` $input | & "$basedir/${slash(exe)}" $args`,
|
|
155
|
+
"} else {",
|
|
156
|
+
` & "$basedir/${slash(exe)}" $args`,
|
|
157
|
+
"}",
|
|
158
|
+
"exit $LASTEXITCODE",
|
|
159
|
+
"",
|
|
160
|
+
].join("\n");
|
|
161
|
+
const files = [
|
|
162
|
+
["pg", `"$basedir/${slash(launcher)}" "$@"`, sh],
|
|
163
|
+
["pg.cmd", `"%dp0%\\${back(launcher)}" %*`, cmd],
|
|
164
|
+
["pg.ps1", `"$basedir/${slash(launcher)}" $args`, ps1],
|
|
165
|
+
];
|
|
166
|
+
for (const [name, viaNode, text] of files) {
|
|
167
|
+
const file = path.join(dir, name);
|
|
168
|
+
let now;
|
|
169
|
+
try {
|
|
170
|
+
now = fs.readFileSync(file, "utf8");
|
|
171
|
+
} catch {
|
|
172
|
+
continue;
|
|
173
|
+
}
|
|
174
|
+
if (now.includes(viaNode)) found.push({ file, text });
|
|
175
|
+
}
|
|
176
|
+
}
|
|
177
|
+
return found;
|
|
178
|
+
}
|
|
179
|
+
|
|
180
|
+
/** Points npm's shims at the binary (Windows); how many were changed. */
|
|
181
|
+
function direct(exe) {
|
|
182
|
+
if (process.platform !== "win32" || !exe || !fs.existsSync(exe)) return 0;
|
|
183
|
+
let changed = 0;
|
|
184
|
+
for (const { file, text } of shims(exe)) {
|
|
185
|
+
const tmp = `${file}.${process.pid}.tmp`;
|
|
186
|
+
try {
|
|
187
|
+
fs.writeFileSync(tmp, text);
|
|
188
|
+
fs.renameSync(tmp, file);
|
|
189
|
+
changed++;
|
|
190
|
+
} catch {
|
|
191
|
+
fs.rmSync(tmp, { force: true });
|
|
192
|
+
}
|
|
193
|
+
}
|
|
194
|
+
return changed;
|
|
195
|
+
}
|
|
196
|
+
|
|
197
|
+
module.exports = { install, binaryPath, assetName, direct };
|
|
94
198
|
|
|
95
199
|
if (require.main === module) {
|
|
96
|
-
install()
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
200
|
+
install()
|
|
201
|
+
.then(direct)
|
|
202
|
+
.catch((e) => {
|
|
203
|
+
// the install itself does not fail: bin/pg tries again on the first call
|
|
204
|
+
process.stderr.write(`paragma: ${e.message}; pg will try again when it first runs.\n`);
|
|
205
|
+
});
|
|
100
206
|
}
|
package/package.json
CHANGED