docks-kit 0.15.0 → 0.15.1

package/README.md

@@ -134,7 +134,7 @@ Details: `docks-kit docs platforms`.
 Tagging `cli-v*` builds four standalone binaries (Linux x64/arm64 and macOS
 x64/arm64) plus `SHA256SUMS` and attaches them to the GitHub release; npm
 publishes the exact package tarball through trusted publishing with OIDC provenance.
-Package `docks-kit` 0.15.0 bundles the CLI + generated payload, so npm releases
+Package `docks-kit` 0.15.1 bundles the CLI + generated payload, so npm releases
 are versioned config snapshots without shipping the authoring `SoT/` tree.
 
 ## Deeper docs

package/cli/docs/install.md

@@ -74,6 +74,24 @@ docks-kit update            # autodetect + update + install-missing-only sync
 docks-kit update --no-sync  # update only
 ```
 
+`docks-kit update` resolves the kit home in this order:
+
+1. The explicit `DOCKS_KIT_HOME` value comes first when set. It must name a
+   directory whose `package.json` has the name `docks-kit`. An invalid value
+   causes an error instead of a fallback.
+2. The CLI uses the nearest kit root at or above its own module directory.
+3. Next, the CLI uses the nearest kit root at or above the directory that holds
+   the executable. A standalone binary inside `<checkout>/cli/dist` therefore
+   resolves to the checkout.
+4. Next, the CLI uses the nearest kit root at or above the current working
+   directory, but only as a fallback.
+5. Otherwise, the CLI uses the directory that holds the executable.
+
+Sources 2 and 3 identify the installation that is running. A globally installed
+`docks-kit` updates the global package even when you run it from inside a
+docks-kit checkout. `DOCKS_KIT_HOME` lets you target a specific checkout on
+purpose.
+
 Autodetection: a kit home with `.git` is a checkout (requires a clean
 worktree and an upstream; `git pull --ff-only`, re-runs
 `bun install --frozen-lockfile` when the lockfile changed); a kit home

package/cli/src/generated/sotPayload.ts

@@ -1,7 +1,7 @@
 // Generated by cli/scripts/generate-sot-payload.ts. DO NOT EDIT.
 // Edit SoT/, notification.mp3, or package.json, then run: bun cli/scripts/generate-sot-payload.ts
 
-export const GENERATED_PACKAGE_VERSION = "0.15.0"
+export const GENERATED_PACKAGE_VERSION = "0.15.1"
 
 export const GENERATED_PAYLOAD_TEXT = {
   "SoT/.agents/skills.txt": "# Universal AI-agent skill manifest intentionally empty.\n# Global skill discovery is opt-in: add one <owner>/<repo> slug per line.\n# EngineNative ignores comments and blank lines.\n",

package/cli/src/kitHome.ts

@@ -10,26 +10,52 @@ const isKitHome = (dir: string): boolean => {
   }
 }
 
-/**
- * Resolve the optional checkout/package home used for display and updates:
- * DOCKS_KIT_HOME env → nearest ancestor of cwd (repo-checkout usage) →
- * the package's own root (bunx / bun add -g usage) → standalone executable
- * directory. Payload availability is independent of this location.
- */
-export const kitHome = (): string => {
-  const env = process.env["DOCKS_KIT_HOME"]
-  if (env !== undefined && env !== "") {
-    if (isKitHome(env)) return resolve(env)
-    throw new Error(`DOCKS_KIT_HOME=${env} is not a docks-kit package root (package.json name must be "docks-kit")`)
-  }
-  let dir = process.cwd()
+const findKitHome = (start: string | undefined): string | undefined => {
+  if (start === undefined || start === "") return undefined
+  let dir = resolve(start)
   for (;;) {
     if (isKitHome(dir)) return dir
     const parent = dirname(dir)
-    if (parent === dir) break
+    if (parent === dir) return undefined
     dir = parent
   }
-  const packageRoot = resolve(import.meta.dir, "..", "..")
-  if (isKitHome(packageRoot)) return packageRoot
-  return dirname(process.execPath)
 }
+
+export interface KitHomeSources {
+  readonly env: string | undefined
+  /** `import.meta.dir` is a Bun extension, so a non-Bun loader leaves it undefined. */
+  readonly moduleDir: string | undefined
+  readonly execPath: string
+  readonly cwd: string
+}
+
+/**
+ * Resolve DOCKS_KIT_HOME, then the nearest kit ancestor of the module,
+ * executable, or working directory, then the executable directory. Running
+ * installation sources take priority so an unrelated checkout cannot replace
+ * the installation that is executing.
+ */
+export const resolveKitHome = (sources: KitHomeSources): string => {
+  if (sources.env !== undefined && sources.env !== "") {
+    const envHome = resolve(sources.env)
+    if (isKitHome(envHome)) return envHome
+    throw new Error(
+      `DOCKS_KIT_HOME=${sources.env} is not a docks-kit package root (package.json name must be "docks-kit")`
+    )
+  }
+
+  return (
+    findKitHome(sources.moduleDir) ??
+    findKitHome(dirname(sources.execPath)) ??
+    findKitHome(sources.cwd) ??
+    dirname(sources.execPath)
+  )
+}
+
+export const kitHome = (): string =>
+  resolveKitHome({
+    env: process.env["DOCKS_KIT_HOME"],
+    moduleDir: import.meta.dir,
+    execPath: process.execPath,
+    cwd: process.cwd()
+  })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docks-kit",
-  "version": "0.15.0",
+  "version": "0.15.1",
   "description": "Portable AI coding agent config kit — SoT sync engine + typed CLI for Claude Code, Codex, and universal agent skills",
   "type": "module",
   "license": "MIT",