docks-kit 0.26.0 → 0.27.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.
@@ -8,7 +8,7 @@ import path from "node:path";
8
8
 
9
9
  import { Effect } from "effect";
10
10
 
11
- import { argumentBytes, utf8Text, workingFolderBytes } from "./bytes";
11
+ import { argumentBytes, asBytes, utf8Text, workingFolderBytes } from "./bytes";
12
12
  import { PlanFiles, PlanProcess, type ProcessOptions, type ProcessResult } from "./services";
13
13
  import type { FileError, SpawnError } from "./types";
14
14
 
@@ -44,12 +44,13 @@ const runGit = Effect.fn("plan.runGit")(function* (
44
44
  /**
45
45
  * The tree-ish of the root of `<commit>` (a byte string), or undefined when git fails. A commit that is UTF-8 text
46
46
  * goes to git as the argument, as under the shell script. Other bytes cannot pass on a command line, so git reads
47
- * `<commit>^{tree}` from stdin and prints the tree id.
47
+ * `<commit>^{tree}` from stdin and prints the tree id. git runs in the folder `cwd`.
48
48
  */
49
- const rootTree = Effect.fn("plan.rootTree")(function* (commit: string) {
49
+ const rootTree = Effect.fn("plan.rootTree")(function* (commit: string, cwd: string | undefined) {
50
50
  const text = utf8Text(commit);
51
51
  if (text !== undefined) return text;
52
52
  const resolved = yield* runGit(["cat-file", "--batch-check=%(objectname)"], {
53
+ cwd,
53
54
  input: Buffer.from(`${commit}^{tree}\n`, "latin1"),
54
55
  });
55
56
  if (!resolved.ok) return undefined;
@@ -71,10 +72,14 @@ interface TreeEntry {
71
72
  /**
72
73
  * The entry `name` of the tree `tree` (a commit names its root tree), undefined when the tree has no such entry, or
73
74
  * 2 when git fails. `ls-tree -z` prints each name unquoted, as its raw bytes, so the name compares byte for byte, and
74
- * no path passes to git.
75
+ * no path passes to git. git runs in the folder `cwd`.
75
76
  */
76
- const treeEntry = Effect.fn("plan.treeEntry")(function* (tree: string, name: string) {
77
- const listed = yield* runGit(["ls-tree", "-z", "--full-tree", tree]);
77
+ const treeEntry = Effect.fn("plan.treeEntry")(function* (
78
+ tree: string,
79
+ name: string,
80
+ cwd: string | undefined,
81
+ ) {
82
+ const listed = yield* runGit(["ls-tree", "-z", "--full-tree", tree], { cwd });
78
83
  if (!listed.ok) return 2 as const;
79
84
  // A record is `<mode> <type> <object id><tab><name>`.
80
85
  for (const record of listed.result.stdout.split("\0")) {
@@ -87,26 +92,22 @@ const treeEntry = Effect.fn("plan.treeEntry")(function* (tree: string, name: str
87
92
  return undefined;
88
93
  });
89
94
 
95
+ /** The blob id that `base-blob` prints, or its exit code without output: 1 absent, 2 a git failure. */
96
+ type BlobLookup = string | 1 | 2;
97
+
90
98
  /**
91
- * `base-blob <commit> <path>`: print the blob id of the file `<path>` in the tree of `<commit>`, as a checkout of
92
- * `<commit>` would open it, and return 0. The arguments are read as bytes. The walk reads one path part at a time and
93
- * looks it up in the listing of the tree that it has reached, by object id. A folder link and a file link resolve
94
- * from the folder that holds the link, and `..` goes to the parent of the real folder that the walk has reached.
95
- * Exit 1: absent (a missing path, a folder, a submodule, a file with more path parts after it, a link with an empty,
96
- * absolute, or outside target, or more than 40 links). Exit 2: a git failure, wrong arguments, or an argument whose
97
- * bytes cannot be recovered (a U+FFFD without /proc, see `bytes.ts`).
99
+ * The walk of `base-blob`: the blob id of the file `target` in the tree of `commit`, as a checkout of `commit` would
100
+ * open it. Both are byte strings. git runs in the folder `cwd`, or in the working folder when `cwd` is undefined. The
101
+ * walk reads one path part at a time and looks it up in the listing of the tree that it has reached, by object id. A
102
+ * folder link and a file link resolve from the folder that holds the link, and `..` goes to the parent of the real
103
+ * folder that the walk has reached. Absent (1): a missing path, a folder, a submodule, a file with more path parts
104
+ * after it, a link with an empty, absolute, or outside target, or more than 40 links. 2: a git failure.
98
105
  */
99
- export const baseBlob = Effect.fn("plan.baseBlob")(function* (args: ReadonlyArray<string>) {
100
- if (args.length !== 2 || !args[0]) {
101
- yield* printError(BASE_BLOB_USAGE);
102
- return 2;
103
- }
104
- const bytes = yield* argumentBytes(args);
105
- if (!bytes.ok) {
106
- yield* printError(`base-blob: ${bytes.cause}`);
107
- return 2;
108
- }
109
- const [commit = "", target = ""] = bytes.value;
106
+ export const resolveBaseBlob = Effect.fn("plan.resolveBaseBlob")(function* (
107
+ commit: string,
108
+ target: string,
109
+ cwd?: string,
110
+ ) {
110
111
  // The root, resolved at the first lookup, then the object id of each folder that the walk has entered; `..` drops
111
112
  // the last one.
112
113
  let root: string | undefined;
@@ -130,9 +131,9 @@ export const baseBlob = Effect.fn("plan.baseBlob")(function* (args: ReadonlyArra
130
131
  trees.pop();
131
132
  continue;
132
133
  }
133
- root ??= yield* rootTree(commit);
134
+ root ??= yield* rootTree(commit, cwd);
134
135
  if (root === undefined) return 2;
135
- const entry = yield* treeEntry(trees.at(-1) ?? root, part);
136
+ const entry = yield* treeEntry(trees.at(-1) ?? root, part, cwd);
136
137
  if (entry === 2) return 2;
137
138
  if (entry === undefined) return 1;
138
139
  switch (entry.mode) {
@@ -142,7 +143,7 @@ export const baseBlob = Effect.fn("plan.baseBlob")(function* (args: ReadonlyArra
142
143
  case "120000": {
143
144
  links += 1;
144
145
  if (links > MAX_LINKS) return 1;
145
- const blob = yield* runGit(["cat-file", "blob", entry.oid]);
146
+ const blob = yield* runGit(["cat-file", "blob", entry.oid], { cwd });
146
147
  if (!blob.ok) return 2;
147
148
  // The raw bytes of the target; its trailing newlines are part of its name.
148
149
  const linkTarget = blob.result.stdout;
@@ -153,10 +154,7 @@ export const baseBlob = Effect.fn("plan.baseBlob")(function* (args: ReadonlyArra
153
154
  case "100644":
154
155
  case "100755":
155
156
  if (rest) return 1;
156
- yield* Effect.sync(() => {
157
- process.stdout.write(`${entry.oid}\n`);
158
- });
159
- return 0;
157
+ return entry.oid;
160
158
  default:
161
159
  return 1;
162
160
  }
@@ -164,6 +162,46 @@ export const baseBlob = Effect.fn("plan.baseBlob")(function* (args: ReadonlyArra
164
162
  return 1;
165
163
  });
166
164
 
165
+ /**
166
+ * `base-blob <commit> <path>`: print the blob id of the file `<path>` in the tree of `<commit>` (`resolveBaseBlob`) and
167
+ * return 0. The arguments are read as bytes. Exit 1: absent. Exit 2: a git failure, wrong arguments, or an argument
168
+ * whose bytes cannot be recovered (a U+FFFD without /proc, see `bytes.ts`).
169
+ */
170
+ export const baseBlob = Effect.fn("plan.baseBlob")(function* (args: ReadonlyArray<string>) {
171
+ if (args.length !== 2 || !args[0]) {
172
+ yield* printError(BASE_BLOB_USAGE);
173
+ return 2;
174
+ }
175
+ const bytes = yield* argumentBytes(args);
176
+ if (!bytes.ok) {
177
+ yield* printError(`base-blob: ${bytes.cause}`);
178
+ return 2;
179
+ }
180
+ const [commit = "", target = ""] = bytes.value;
181
+ const blob: BlobLookup = yield* resolveBaseBlob(commit, target);
182
+ if (blob === 1 || blob === 2) return blob;
183
+ yield* Effect.sync(() => {
184
+ process.stdout.write(`${blob}\n`);
185
+ });
186
+ return 0;
187
+ });
188
+
189
+ /**
190
+ * `resolveBaseBlob` in this process, for a synchronous caller outside the CLI: the review-benchmark scripts read many
191
+ * instruction files, and one CLI process per file costs a Bun start each. `commit` and `target` are UTF-8 text; git
192
+ * runs in the repository folder `cwd` and prints its errors on stderr. A git that could not start is a failure (2), as
193
+ * under `docks-kit plan base-blob`.
194
+ */
195
+ export const baseBlobSync = (cwd: string, commit: string, target: string): BlobLookup =>
196
+ Effect.runSync(
197
+ resolveBaseBlob(asBytes(commit), asBytes(target), cwd).pipe(
198
+ Effect.catchTag("SpawnError", (error) =>
199
+ printError(error.message).pipe(Effect.as(2 as const)),
200
+ ),
201
+ Effect.provide(PlanProcess.layer),
202
+ ),
203
+ );
204
+
167
205
  /** The sorted listing lines of a checkout, or the exit code of a failed listing. */
168
206
  type Listing = ReadonlyArray<string> | 1 | 2;
169
207
 
package/docks-kit CHANGED
@@ -1,59 +1,28 @@
1
1
  #!/bin/bash
2
- # docks-kit — launcher. Resolution order:
3
- # 1. version-matching compiled binary in cli/dist/ (bun build --compile output)
4
- # 2. Bun from source (auto-installs Bun + node_modules when missing)
5
- # No-Bun recovery path: download a release binary for your platform.
2
+ # docks-kit - checkout launcher. It runs cli/src/main.ts with Bun and
3
+ # installs Bun and node_modules when they are missing.
6
4
  set -euo pipefail
7
5
 
8
6
  REPO_DIR="$(cd "$(dirname "$0")" && pwd)"
9
7
 
10
8
  # BEGIN GENERATED BUN PIN
11
- BUN_PIN="1.4.4"
9
+ BUN_PIN="1.4.5"
12
10
  # END GENERATED BUN PIN
13
11
 
14
12
  # BEGIN GENERATED BUN FLOOR
15
- BUN_FLOOR="1.4.4"
13
+ BUN_FLOOR="1.4.5"
16
14
  # END GENERATED BUN FLOOR
17
15
 
16
+ # Reject an unsupported host before the Bun install, so that the user gets
17
+ # one clear message instead of a failed download or a failed source run.
18
18
  HOST="$(uname -s)-$(uname -m)"
19
19
  case "$HOST" in
20
- Linux-x86_64) KIT_BIN="docks-kit-linux-x64" ;;
21
- Linux-aarch64) KIT_BIN="docks-kit-linux-arm64" ;;
22
- Darwin-arm64) KIT_BIN="docks-kit-darwin-arm64" ;;
20
+ Linux-x86_64 | Linux-aarch64 | Darwin-arm64) ;;
23
21
  *)
24
22
  echo "[docks-kit] unsupported host $HOST; docks-kit supports Linux on x64 and arm64, macOS on arm64, and Windows on x64 - on Windows run docks-kit.ps1 instead." >&2
25
23
  exit 1
26
24
  ;;
27
25
  esac
28
- if [[ -x "$REPO_DIR/cli/dist/$KIT_BIN" ]]; then
29
- CHECKOUT_VERSION=""
30
- while IFS= read -r line; do
31
- if [[ "$line" =~ ^[[:space:]]*\"version\"[[:space:]]*:[[:space:]]*\"([^\"]+)\" ]]; then
32
- CHECKOUT_VERSION="${BASH_REMATCH[1]}"
33
- break
34
- fi
35
- done < "$REPO_DIR/package.json"
36
- BIN_VERSION="$("$REPO_DIR/cli/dist/$KIT_BIN" --version 2>/dev/null || true)"
37
- BIN_VERSION="${BIN_VERSION%$'\r'}"
38
- if [[ -n "$CHECKOUT_VERSION" && "$BIN_VERSION" == "$CHECKOUT_VERSION" ]]; then
39
- # A matching version does not prove matching content. Unreleased work does
40
- # not move package.json, so a binary compiled before it still reports the
41
- # checkout version and would silently shadow the source it predates.
42
- # The binary also embeds the cli/docs topics, so scan both trees.
43
- NEWER_SOURCE=""
44
- for scan_dir in "$REPO_DIR/cli/src" "$REPO_DIR/cli/docs"; do
45
- if [[ -z "$NEWER_SOURCE" && -d "$scan_dir" ]]; then
46
- NEWER_SOURCE="$(find "$scan_dir" -type f -newer "$REPO_DIR/cli/dist/$KIT_BIN" -print -quit 2>/dev/null || true)"
47
- fi
48
- done
49
- if [[ -z "$NEWER_SOURCE" ]]; then
50
- exec "$REPO_DIR/cli/dist/$KIT_BIN" "$@"
51
- fi
52
- echo "[docks-kit] ignoring cli/dist/$KIT_BIN; ${NEWER_SOURCE#"$REPO_DIR/"} is newer than the binary — running from source; run 'bun run build:binaries' to refresh it or delete it" >&2
53
- else
54
- echo "[docks-kit] ignoring stale cli/dist/$KIT_BIN ${BIN_VERSION:-<unknown>}; checkout is ${CHECKOUT_VERSION:-<unknown>} — running from source; run 'bun run build:binaries' to refresh it or delete it" >&2
55
- fi
56
- fi
57
26
 
58
27
  # Locate bun: PATH, then the known install locations that sit off the
59
28
  # non-interactive PATH (~/.bun/bin, ~/.local/bin).
@@ -99,7 +68,7 @@ bun_version_at_least() {
99
68
  if ! BUN="$(find_bun)"; then
100
69
  echo "[docks-kit] Bun not found — installing (download-then-run)..." >&2
101
70
  if ! command -v curl >/dev/null 2>&1; then
102
- echo "[docks-kit] curl missing too. Install Bun manually (https://bun.sh) or download a docks-kit release binary." >&2
71
+ echo "[docks-kit] curl missing too. Install Bun manually from https://bun.sh, then run docks-kit again." >&2
103
72
  exit 1
104
73
  fi
105
74
  # The installer takes a bun-vX.Y.Z release tag as $1. BUN_PIN is generated
@@ -108,7 +77,7 @@ if ! BUN="$(find_bun)"; then
108
77
  curl -fsSL https://bun.sh/install -o "$tmp_installer" && bash "$tmp_installer" ${BUN_PIN:+"bun-v$BUN_PIN"} >/dev/null 2>&1 || true
109
78
  rm -f "$tmp_installer"
110
79
  if ! BUN="$(find_bun)"; then
111
- echo "[docks-kit] Bun install failed. Download a docks-kit release binary for a no-Bun recovery path." >&2
80
+ echo "[docks-kit] Bun install failed. Install Bun manually from https://bun.sh, then run docks-kit again." >&2
112
81
  exit 1
113
82
  fi
114
83
  fi
package/docks-kit.ps1 CHANGED
@@ -1,20 +1,20 @@
1
- # docks-kit.ps1 - Windows launcher. Resolution order:
2
- # 1. version-matching compiled binary in cli/dist/ (bun build --compile output)
3
- # 2. Bun from source (auto-installs Bun + node_modules when missing)
4
- # No-Bun recovery path: download a release binary for your platform.
1
+ # docks-kit.ps1 - Windows checkout launcher. It runs cli\src\main.ts with Bun
2
+ # and installs Bun and node_modules when they are missing.
5
3
  Set-StrictMode -Version Latest
6
4
  $ErrorActionPreference = 'Stop'
7
5
 
8
6
  $RepoDir = Split-Path -Parent $MyInvocation.MyCommand.Path
9
7
 
10
8
  # BEGIN GENERATED BUN PIN
11
- $BunPin = "1.4.4"
9
+ $BunPin = "1.4.5"
12
10
  # END GENERATED BUN PIN
13
11
 
14
12
  # BEGIN GENERATED BUN FLOOR
15
- $BunFloor = "1.4.4"
13
+ $BunFloor = "1.4.5"
16
14
  # END GENERATED BUN FLOOR
17
15
 
16
+ # Reject an unsupported host before the Bun install, so that the user gets
17
+ # one clear message instead of a failed download or a failed source run.
18
18
  $ProcessorArchitecture = if (-not [string]::IsNullOrWhiteSpace($env:PROCESSOR_ARCHITEW6432)) {
19
19
  $env:PROCESSOR_ARCHITEW6432
20
20
  } else {
@@ -23,8 +23,8 @@ $ProcessorArchitecture = if (-not [string]::IsNullOrWhiteSpace($env:PROCESSOR_AR
23
23
  if ([string]::IsNullOrWhiteSpace($ProcessorArchitecture)) {
24
24
  $ProcessorArchitecture = '<unknown>'
25
25
  }
26
- $KitBin = switch ($ProcessorArchitecture) {
27
- 'AMD64' { 'docks-kit-windows-x64.exe' }
26
+ switch ($ProcessorArchitecture) {
27
+ 'AMD64' { }
28
28
  default {
29
29
  $HostName = "Windows-$ProcessorArchitecture"
30
30
  [Console]::Error.WriteLine("[docks-kit] unsupported host $HostName; docks-kit supports Linux on x64 and arm64, macOS on arm64, and Windows on x64.")
@@ -32,57 +32,6 @@ $KitBin = switch ($ProcessorArchitecture) {
32
32
  }
33
33
  }
34
34
 
35
- $KitPath = Join-Path (Join-Path $RepoDir 'cli\dist') $KitBin
36
- if (Test-Path -LiteralPath $KitPath -PathType Leaf) {
37
- $CheckoutVersion = ''
38
- try {
39
- $Manifest = Get-Content -LiteralPath (Join-Path $RepoDir 'package.json') -Raw | ConvertFrom-Json
40
- if ($Manifest.version -is [string]) {
41
- $CheckoutVersion = $Manifest.version
42
- }
43
- } catch {
44
- $CheckoutVersion = ''
45
- }
46
-
47
- $BinVersion = ''
48
- try {
49
- $BinOutput = & $KitPath --version 2>$null
50
- if ($LASTEXITCODE -eq 0) {
51
- $BinVersion = ([string]($BinOutput -join "`n")).TrimEnd("`r")
52
- }
53
- } catch {
54
- $BinVersion = ''
55
- }
56
-
57
- if (-not [string]::IsNullOrEmpty($CheckoutVersion) -and $BinVersion -eq $CheckoutVersion) {
58
- # A matching version does not prove matching content. Unreleased work does
59
- # not move package.json, so a binary compiled before it still reports the
60
- # checkout version and would silently shadow the source it predates.
61
- # The binary also embeds the cli/docs topics, so scan both trees.
62
- $NewerSource = $null
63
- $ScanDirs = @(
64
- @((Join-Path $RepoDir 'cli\src'), (Join-Path $RepoDir 'cli\docs')) |
65
- Where-Object { Test-Path -LiteralPath $_ -PathType Container }
66
- )
67
- if ($ScanDirs.Count -gt 0) {
68
- $BinWritten = (Get-Item -LiteralPath $KitPath).LastWriteTimeUtc
69
- $NewerSource = Get-ChildItem -LiteralPath $ScanDirs -Recurse -File -ErrorAction SilentlyContinue |
70
- Where-Object { $_.LastWriteTimeUtc -gt $BinWritten } |
71
- Select-Object -First 1
72
- }
73
- if ($null -eq $NewerSource) {
74
- & $KitPath @args
75
- exit $LASTEXITCODE
76
- }
77
- $NewerRelative = $NewerSource.FullName.Substring($RepoDir.Length).TrimStart('\', '/')
78
- [Console]::Error.WriteLine("[docks-kit] ignoring cli/dist/$KitBin; $NewerRelative is newer than the binary - running from source; run 'bun run build:binaries' to refresh it or delete it")
79
- } else {
80
- $DisplayedBinVersion = if ([string]::IsNullOrEmpty($BinVersion)) { '<unknown>' } else { $BinVersion }
81
- $DisplayedCheckoutVersion = if ([string]::IsNullOrEmpty($CheckoutVersion)) { '<unknown>' } else { $CheckoutVersion }
82
- [Console]::Error.WriteLine("[docks-kit] ignoring stale cli/dist/$KitBin $DisplayedBinVersion; checkout is $DisplayedCheckoutVersion - running from source; run 'bun run build:binaries' to refresh it or delete it")
83
- }
84
- }
85
-
86
35
  function Find-Bun {
87
36
  $Command = Get-Command bun -CommandType Application -ErrorAction SilentlyContinue | Select-Object -First 1
88
37
  if ($null -ne $Command) {
@@ -115,13 +64,13 @@ if ($null -eq $Bun) {
115
64
  # upstream documents, matching os/windows.ts bunInstaller.
116
65
  & powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -File $TempInstaller -Version $BunPin *> $null
117
66
  } catch {
118
- # The recovery guidance below is shared by download and installer failures.
67
+ # The install guidance below is shared by download and installer failures.
119
68
  } finally {
120
69
  Remove-Item -LiteralPath $TempInstaller -Force -ErrorAction SilentlyContinue
121
70
  }
122
71
  $Bun = Find-Bun
123
72
  if ($null -eq $Bun) {
124
- [Console]::Error.WriteLine('[docks-kit] Bun install failed. Download a docks-kit release binary for a no-Bun recovery path.')
73
+ [Console]::Error.WriteLine('[docks-kit] Bun install failed. Install Bun manually from https://bun.sh, then run docks-kit again.')
125
74
  exit 1
126
75
  }
127
76
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "docks-kit",
3
- "version": "0.26.0",
3
+ "version": "0.27.0",
4
4
  "description": "Portable AI coding agent config kit — SoT sync engine + typed CLI for Oh My Pi",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -28,16 +28,15 @@
28
28
  ],
29
29
  "scripts": {
30
30
  "typecheck": "bun check --no-script -b -p cli",
31
- "build:binaries": "bash cli/build-binaries.sh",
32
31
  "build:bundle": "bun cli/scripts/build-bundle.ts",
33
- "smoke:native": "bun cli/scripts/native-smoke.ts",
34
32
  "smoke:package": "bun cli/scripts/package-smoke.ts",
35
33
  "check:generated": "bun cli/scripts/generate-sot-payload.ts --check",
36
34
  "prepack": "bun run check:generated && bun run build:bundle",
37
35
  "golden:dryrun": "bun cli/test/golden-dryrun.ts",
38
36
  "golden:mutation": "bun cli/test/golden-mutation.ts",
39
37
  "test:unit": "vitest run",
40
- "test:ci": "bun run check:generated && bun run --parallel typecheck test:unit golden:dryrun golden:mutation format:check",
38
+ "test:unit:portable": "vitest run --project unit --project backstop",
39
+ "test:ci": "bun run check:generated && bun run --parallel typecheck test:unit:portable golden:dryrun golden:mutation format:check",
41
40
  "test:integration": "bun run --parallel golden:dryrun golden:mutation",
42
41
  "test": "bun run --parallel test:unit test:integration",
43
42
  "lint": "oxlint",
@@ -54,7 +53,7 @@
54
53
  },
55
54
  "devDependencies": {
56
55
  "@effect/tsgo": "0.64.1",
57
- "@types/bun": "1.4.4",
56
+ "@types/bun": "1.4.5",
58
57
  "fast-check": "4.10.2",
59
58
  "oxlint": "1.91.0",
60
59
  "typescript": "7.0.2",