@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.2` remains a preview; `latest` and `next` identify the current preview release.
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
- Supported installer preview: Linux; macOS uses POSIX hooks but still needs platform validation. Native Windows installation is explicitly blocked pending implementation and tests; WSL can use the Linux path. Claude Desktop currently receives a configuration fragment requiring a manual merge into Desktop settings. No universal client compatibility is claimed.
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
- "env",
138
- ...Object.entries({
139
- ...env,
140
- MEMORY_QUEUE: join(dirname(opts.database), "queue", client),
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?.includes("MEMORY_MANAGED=shared-agent-memory")));
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?.includes("MEMORY_MANAGED=shared-agent-memory"))))
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
- execFileSync("npm", [
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
- ], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 180_000 });
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.2` remains a preview. Both `latest` and `next` track the current preview release.
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.2.tgz knitt setup \
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.2.tgz
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` (platform validation pending).
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.2` includes opt-in local conversation memory. Native Windows setup deliberately fails rather than writing POSIX hook commands. Linux tarball checks are the local verification target; macOS/Windows live client behavior remains unverified.
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
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tinchu0/knitt",
3
- "version": "0.1.0-beta.2",
3
+ "version": "0.1.0-beta.3",
4
4
  "type": "module",
5
5
  "engines": {
6
6
  "node": ">=24"