@tinchu0/knitt 0.1.0-beta.2 → 0.1.0-beta.3
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
|
@@ -18,9 +18,9 @@ npx @tinchu0/knitt@latest setup \
|
|
|
18
18
|
--capture-new-sessions
|
|
19
19
|
```
|
|
20
20
|
|
|
21
|
-
Setup shows configuration changes before applying them and installs a persistent runtime in your user data directory. Restart agents and approve their normal MCP/hook trust prompts. The npm installation path does not require Python or a source checkout. Version `0.1.0-beta.
|
|
21
|
+
Setup shows configuration changes before applying them and installs a persistent runtime in your user data directory. Restart agents and approve their normal MCP/hook trust prompts. The npm installation path does not require Python or a source checkout. Version `0.1.0-beta.3` remains a preview; `latest` and `next` identify the current preview release.
|
|
22
22
|
|
|
23
|
-
|
|
23
|
+
The installer includes native Linux, macOS and Windows paths. Windows hooks use built-in Windows PowerShell; macOS and Linux use POSIX hooks. CI runs the full suite and packaged lifecycle checks on all three operating systems. Live application handoffs still require client-specific validation. Claude Desktop currently receives a configuration fragment requiring a manual merge into Desktop settings. No universal client compatibility is claimed.
|
|
24
24
|
|
|
25
25
|
See [npm installation and lifecycle](docs/clients/npm-installation.md) and [remote connector setup](docs/clients/connector-setup.md).
|
|
26
26
|
|
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { hookCommand, isManagedHook } from "./platform.js";
|
|
1
2
|
import { readFileSync, existsSync, mkdirSync, writeFileSync, renameSync, rmSync, realpathSync, } from "node:fs";
|
|
2
3
|
import { join, dirname, resolve } from "node:path";
|
|
3
4
|
import { execFileSync } from "node:child_process";
|
|
@@ -96,8 +97,6 @@ export function readConnectionState(workspace) {
|
|
|
96
97
|
return value;
|
|
97
98
|
}
|
|
98
99
|
export function planConnection(opts) {
|
|
99
|
-
if (process.platform === "win32")
|
|
100
|
-
throw new Error("Windows hook installation is not yet validated. Use WSL for this preview.");
|
|
101
100
|
const workspace = realpathSync(opts.workspace), app = resolve(opts.appRoot), node = opts.node ?? process.execPath;
|
|
102
101
|
if (!opts.clients.length ||
|
|
103
102
|
opts.clients.some((c) => !clients.includes(c)))
|
|
@@ -129,24 +128,14 @@ export function planConnection(opts) {
|
|
|
129
128
|
? { MEMORY_CONVERSATION_MODE: "1", MEMORY_CAPTURE_NEW_SESSIONS: "1" }
|
|
130
129
|
: {}),
|
|
131
130
|
};
|
|
132
|
-
const quote = (s) => "'" + s.replaceAll("'", "'\\''") + "'";
|
|
133
131
|
const handler = (client, action) => ({
|
|
134
132
|
type: "command",
|
|
135
133
|
timeout: 10,
|
|
136
|
-
command:
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
MEMORY_MANAGED: "shared-agent-memory",
|
|
142
|
-
}).map(([k, v]) => k + "=" + v),
|
|
143
|
-
node,
|
|
144
|
-
runner,
|
|
145
|
-
action,
|
|
146
|
-
client,
|
|
147
|
-
]
|
|
148
|
-
.map(quote)
|
|
149
|
-
.join(" "),
|
|
134
|
+
command: hookCommand({
|
|
135
|
+
...env,
|
|
136
|
+
MEMORY_QUEUE: join(dirname(opts.database), "queue", client),
|
|
137
|
+
MEMORY_MANAGED: "shared-agent-memory",
|
|
138
|
+
}, node, [runner, action, client]),
|
|
150
139
|
});
|
|
151
140
|
const connection = (desktop = false, client = "claude") => {
|
|
152
141
|
const clientEnv = {
|
|
@@ -193,9 +182,9 @@ export function planConnection(opts) {
|
|
|
193
182
|
throw new Error("Invalid hooks in " + path);
|
|
194
183
|
// Only remove exact previously generated handlers. Edited handlers remain;
|
|
195
184
|
// reject if they mention our runner to avoid duplicate capture.
|
|
196
|
-
const oldOwned = old.filter((g) => g.hooks?.some((h) => h.command
|
|
185
|
+
const oldOwned = old.filter((g) => g.hooks?.some((h) => isManagedHook(h.command)));
|
|
197
186
|
const kept = groups.filter((g) => !oldOwned.some((p) => equal(p, g)));
|
|
198
|
-
if (kept.some((g) => g.hooks?.some((h) => h.command
|
|
187
|
+
if (kept.some((g) => g.hooks?.some((h) => isManagedHook(h.command))))
|
|
199
188
|
throw new Error("Modified hook conflict in " + path);
|
|
200
189
|
value.hooks[event] = [...kept, { hooks: [handler(client, action)] }];
|
|
201
190
|
}
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
import { existsSync } from 'node:fs';
|
|
2
|
+
import { dirname, join } from 'node:path';
|
|
3
|
+
/** Resolve npm's JavaScript entry point on Windows: execFile cannot run npm.cmd.
|
|
4
|
+
* All package arguments stay in an argv array, never a command shell. */
|
|
5
|
+
export function npmCommand(args, options = {}) {
|
|
6
|
+
const platform = options.platform ?? process.platform, env = options.env ?? process.env, node = options.node ?? process.execPath;
|
|
7
|
+
if (platform !== 'win32')
|
|
8
|
+
return { command: 'npm', args };
|
|
9
|
+
const path = Object.entries(env).find(([key]) => key.toLowerCase() === 'path')?.[1] ?? '';
|
|
10
|
+
const candidates = [
|
|
11
|
+
...(env.npm_execpath ? [join(dirname(env.npm_execpath), 'npm-cli.js')] : []),
|
|
12
|
+
join(dirname(node), 'node_modules/npm/bin/npm-cli.js'),
|
|
13
|
+
...path.split(';').filter(Boolean).map(directory => join(directory.replace(/^"|"$/g, ''), 'node_modules/npm/bin/npm-cli.js')),
|
|
14
|
+
];
|
|
15
|
+
const cli = candidates.find(candidate => existsSync(candidate));
|
|
16
|
+
if (!cli)
|
|
17
|
+
throw new Error('Cannot locate npm. Install Node.js 24+ with npm and add it to PATH.');
|
|
18
|
+
return { command: node, args: [cli, ...args] };
|
|
19
|
+
}
|
|
20
|
+
const marker = 'MEMORY_MANAGED=shared-agent-memory';
|
|
21
|
+
const powershell = 'powershell.exe -NoLogo -NoProfile -NonInteractive -EncodedCommand ';
|
|
22
|
+
/** Serialize a hook for the host shell without interpolating data as code. */
|
|
23
|
+
export function hookCommand(env, node, args, platform = process.platform) {
|
|
24
|
+
if (platform !== 'win32') {
|
|
25
|
+
const quote = (s) => "'" + s.replaceAll("'", "'\\''") + "'";
|
|
26
|
+
return ['env', ...Object.entries(env).map(([key, value]) => key + '=' + value), node, ...args].map(quote).join(' ');
|
|
27
|
+
}
|
|
28
|
+
const quote = (s) => "'" + s.replaceAll("'", "''") + "'";
|
|
29
|
+
// EncodedCommand avoids cmd.exe expanding %, &, or Unicode paths. PowerShell
|
|
30
|
+
// invokes Node directly with inherited stdin; no pipeline re-encodes hook JSON.
|
|
31
|
+
const assignments = Object.entries(env).map(([key, value]) => {
|
|
32
|
+
if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key))
|
|
33
|
+
throw new Error('Invalid hook environment key');
|
|
34
|
+
return '$env:' + key + '=' + quote(value) + ';';
|
|
35
|
+
}).join('');
|
|
36
|
+
const script = '[Console]::InputEncoding=[Console]::OutputEncoding=New-Object System.Text.UTF8Encoding;' +
|
|
37
|
+
assignments + '& ' + [node, ...args].map(quote).join(' ') + ';exit $LASTEXITCODE';
|
|
38
|
+
return powershell + Buffer.from(script, 'utf16le').toString('base64');
|
|
39
|
+
}
|
|
40
|
+
export function isManagedHook(command) {
|
|
41
|
+
if (typeof command !== 'string')
|
|
42
|
+
return false;
|
|
43
|
+
if (command.includes(marker))
|
|
44
|
+
return true; // Existing POSIX installations.
|
|
45
|
+
// PowerShell switches are case-insensitive and can be abbreviated/reordered.
|
|
46
|
+
// Recognize the payload even after a launcher edit so setup rejects conflicts.
|
|
47
|
+
for (const match of command.matchAll(/(?:^|\s)-([a-z]+)\s+(['"]?)([a-z0-9+/=]+)\2(?=\s|$)/gi)) {
|
|
48
|
+
if (!'encodedcommand'.startsWith(match[1].toLowerCase()))
|
|
49
|
+
continue;
|
|
50
|
+
const script = Buffer.from(match[3], 'base64').toString('utf16le');
|
|
51
|
+
if (/\$env:MEMORY_MANAGED\s*=\s*(['"])shared-agent-memory\1\s*;/i.test(script))
|
|
52
|
+
return true;
|
|
53
|
+
}
|
|
54
|
+
return false;
|
|
55
|
+
}
|
|
@@ -3,6 +3,7 @@ import { homedir } from "node:os";
|
|
|
3
3
|
import { join, resolve } from "node:path";
|
|
4
4
|
import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, mkdtempSync, writeFileSync, } from "node:fs";
|
|
5
5
|
import { execFileSync } from "node:child_process";
|
|
6
|
+
import { npmCommand } from "./platform.js";
|
|
6
7
|
import { randomUUID } from "node:crypto";
|
|
7
8
|
import { atomicWrite } from "./connections.js";
|
|
8
9
|
export const packageName = "@tinchu0/knitt";
|
|
@@ -52,8 +53,6 @@ export async function withInstallLock(home, work) {
|
|
|
52
53
|
}
|
|
53
54
|
}
|
|
54
55
|
export function installRuntime(home, spec) {
|
|
55
|
-
if (process.platform === "win32")
|
|
56
|
-
throw new Error("Windows installer validation is pending; use WSL for this preview.");
|
|
57
56
|
if (Number(process.versions.node.split(".")[0]) < 24)
|
|
58
57
|
throw new Error("Node.js 24 or newer is required");
|
|
59
58
|
const paths = runtimePaths(home);
|
|
@@ -63,7 +62,7 @@ export function installRuntime(home, spec) {
|
|
|
63
62
|
try {
|
|
64
63
|
writeFileSync(join(staging, "package.json"), JSON.stringify({ name: "shared-memory-runtime", private: true }), { mode: 0o600 });
|
|
65
64
|
// Arguments are passed directly; no shell interpolation or install lifecycle scripts.
|
|
66
|
-
|
|
65
|
+
const npm = npmCommand([
|
|
67
66
|
"install",
|
|
68
67
|
"--prefix",
|
|
69
68
|
staging,
|
|
@@ -74,7 +73,8 @@ export function installRuntime(home, spec) {
|
|
|
74
73
|
"--save-exact",
|
|
75
74
|
"--",
|
|
76
75
|
spec,
|
|
77
|
-
]
|
|
76
|
+
]);
|
|
77
|
+
execFileSync(npm.command, npm.args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 180_000 });
|
|
78
78
|
const root = join(staging, "node_modules", packageName);
|
|
79
79
|
const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
|
|
80
80
|
if (pkg.name !== packageName ||
|
|
@@ -9,26 +9,45 @@ npx @tinchu0/knitt@latest setup \
|
|
|
9
9
|
--workspace /path/to/project --client codex --client claude-code
|
|
10
10
|
```
|
|
11
11
|
|
|
12
|
-
Add `--capture-new-sessions` to opt into independent local conversation histories and checkpoint-first handoffs. Version `0.1.0-beta.
|
|
12
|
+
Add `--capture-new-sessions` to opt into independent local conversation histories and checkpoint-first handoffs. Version `0.1.0-beta.3` remains a preview. Both `latest` and `next` track the current preview release.
|
|
13
13
|
|
|
14
14
|
To test a source checkout before publication, run `npm ci`, `npm run check`, `npm run build` and `npm pack`, then install its exact artifact:
|
|
15
15
|
|
|
16
16
|
```bash
|
|
17
|
-
npx --yes --package ./tinchu0-knitt-0.1.0-beta.
|
|
17
|
+
npx --yes --package ./tinchu0-knitt-0.1.0-beta.3.tgz knitt setup \
|
|
18
18
|
--workspace /path/to/project --client codex --client claude-code \
|
|
19
|
-
--package /absolute/path/to/tinchu0-knitt-0.1.0-beta.
|
|
19
|
+
--package /absolute/path/to/tinchu0-knitt-0.1.0-beta.3.tgz
|
|
20
20
|
```
|
|
21
21
|
|
|
22
22
|
The outer `--package` selects the CLI; the `--package` after `setup` selects the artifact to install persistently. Without that inner option, setup installs the CLI's exact published version. `update` follows `next` for prerelease CLIs and `latest` for stable CLIs.
|
|
23
23
|
|
|
24
24
|
Use `--preview` to inspect changes without creating installation/configuration files. Interactive setup asks before applying; automation must pass `--yes`. Repeat `--client` for several agents. Setup requires Git repository metadata to derive a stable repository identity.
|
|
25
25
|
|
|
26
|
+
## Native platform setup
|
|
27
|
+
|
|
28
|
+
Install Node.js 24+ with npm and Git, and add them to PATH. Windows hooks use built-in Windows PowerShell 5.1 (`powershell.exe` on PATH); no WSL or Python is needed for npm installation. macOS and Linux hooks use their POSIX shell.
|
|
29
|
+
|
|
30
|
+
Windows PowerShell example (one line):
|
|
31
|
+
|
|
32
|
+
```powershell
|
|
33
|
+
npx @tinchu0/knitt@latest setup --workspace "C:\Users\you\My Project" --client codex --client claude-code --capture-new-sessions
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
macOS example:
|
|
37
|
+
|
|
38
|
+
```sh
|
|
39
|
+
npx @tinchu0/knitt@latest setup --workspace "$HOME/Projects/My Project" --client codex --client claude-code --capture-new-sessions
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Existing installations can run `npx @tinchu0/knitt@latest update --yes`. Restart connected agents afterward and approve their normal hook/MCP trust prompts. Update retains memory and the existing capture preference. For Claude Desktop, merge the generated fragment into Desktop settings manually.
|
|
43
|
+
|
|
26
44
|
## Durable installation
|
|
27
45
|
|
|
28
46
|
The default installation directory is:
|
|
29
47
|
|
|
30
48
|
- Linux: `$XDG_DATA_HOME/shared-agent-memory` or `~/.local/share/shared-agent-memory`.
|
|
31
|
-
- macOS: `~/Library/Application Support/SharedAgentMemory
|
|
49
|
+
- macOS: `~/Library/Application Support/SharedAgentMemory`.
|
|
50
|
+
- Windows: `%LOCALAPPDATA%\SharedAgentMemory`, falling back to `~\AppData\Local\SharedAgentMemory`.
|
|
32
51
|
|
|
33
52
|
Override with `SHARED_MEMORY_HOME` or `--home /absolute/path`. The directory contains private `data/`, versioned runtime installations and `installation.json`. Node and runtime paths in generated settings are absolute. Upgrading/removing Node itself can invalidate the executable path; rerun setup with the new Node installation.
|
|
34
53
|
|
|
@@ -57,7 +76,7 @@ Uninstall restores unchanged managed values and preserves independent additions
|
|
|
57
76
|
|
|
58
77
|
## Release gates
|
|
59
78
|
|
|
60
|
-
The package is `@tinchu0/knitt`, published under npm account `tinchu0`, with Apache-2.0 licensing. The LICENSE file ships in the npm archive. Release `0.1.0-beta.
|
|
79
|
+
The package is `@tinchu0/knitt`, published under npm account `tinchu0`, with Apache-2.0 licensing. The LICENSE file ships in the npm archive. Release `0.1.0-beta.3` retains opt-in local conversation memory and adds native Windows installation and hooks. Windows npm installation invokes the npm JavaScript entry point directly, keeping package arguments outside a shell. The CI matrix covers Linux, macOS and Windows; live client behavior is separate from packaged lifecycle verification.
|
|
61
80
|
|
|
62
81
|
ChatGPT, Claude web and teammate machines require a separately reachable authenticated service. Packaging a CLI does not supply hosting, authentication accounts or background synchronization.
|
|
63
82
|
|