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 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,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
- ac7470a922978675b69cf1a67763e4e63390a0f34de2a61f0a936e55006927b9 pg-darwin-arm64
2
- b417037c9d74dde89ea94fe206f86f894f5133d16472fbbe06ec3e46f19bf65d pg-darwin-x64
3
- 59706071418fb642f92d9e40fb9d844bec545aec2a1b2eef501a9da9ae28213a pg-linux-arm64
4
- ee03e0a9ddbc3cf4dfdbfd8c971b8a3ee8f76ed41d1ec8e399de3c89f7581425 pg-linux-x64
5
- 9aaf122ad21b4b58f1749e9e9b43dd6a01adc36f9fc90dc0b5ac9d7a87cc92b5 pg-windows-arm64.exe
6
- 33c6cd65069e7d3c4b4d1327d3e388dfbdba7c5254790616e02b2e0cf890c395 pg-windows-x64.exe
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
- module.exports = { install, binaryPath, assetName };
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().catch((e) => {
97
- // the install itself does not fail: bin/pg tries again on the first call
98
- process.stderr.write(`paragma: ${e.message}; pg will try again when it first runs.\n`);
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "paragma",
3
- "version": "0.2.6",
3
+ "version": "0.3.0",
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",