docks-kit 0.20.10 → 0.21.1

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.
@@ -1,21 +1,31 @@
1
1
  /**
2
- * EngineNative omp plugin pass: marketplace-plugin install/upgrade plus the
3
- * pinned pi-intercom npm plugin. Split from ompSync.ts; the orchestration
4
- * still lives there.
2
+ * EngineNative omp plugin pass: marketplace-plugin install/upgrade, the
3
+ * pinned pi-intercom npm plugin, and the link of the kit plugin that
4
+ * `ompKitPlugin.ts syncKitPlugin` writes. Split from ompSync.ts; the
5
+ * orchestration still lives there.
5
6
  */
7
+ import { realpathSync } from "node:fs";
8
+
6
9
  import { processFailureSummary, spawnProcess } from "./exec";
7
10
  import { recordFailure } from "./failures";
8
11
  import type { Ctx } from "./index";
9
12
  import { isObject, parseJson } from "./jq";
13
+ import { KIT_PLUGIN_NAME, kitPluginDir } from "./ompKitPlugin";
10
14
  import { field } from "./toolchain";
11
15
 
12
16
  const MARKETPLACE_PLUGIN_IDS = ["docks@docks", "plan-lifecycle@docks"] as const;
13
17
 
14
18
  // -------------------------------------------------------------- plugins ----
15
19
 
20
+ interface InstalledNpmPlugin {
21
+ readonly version: string;
22
+ /** The `node_modules` entry of the plugin, a symbolic link for a linked plugin. */
23
+ readonly path: string | undefined;
24
+ }
25
+
16
26
  interface InstalledPlugins {
17
27
  readonly marketplace: Set<string>;
18
- readonly npm: Map<string, string>;
28
+ readonly npm: Map<string, InstalledNpmPlugin>;
19
29
  }
20
30
 
21
31
  async function installedPluginIdsFromCli(): Promise<InstalledPlugins | undefined> {
@@ -46,11 +56,12 @@ async function installedPluginIdsFromCli(): Promise<InstalledPlugins | undefined
46
56
  marketplace.add(row["id"]);
47
57
  }
48
58
 
49
- const npm = new Map<string, string>();
59
+ const npm = new Map<string, InstalledNpmPlugin>();
50
60
  for (const row of value["npm"]) {
51
61
  if (!isObject(row) || typeof row["name"] !== "string" || typeof row["version"] !== "string")
52
62
  continue;
53
- npm.set(row["name"], row["version"]);
63
+ const path = typeof row["path"] === "string" ? row["path"] : undefined;
64
+ npm.set(row["name"], { version: row["version"], path });
54
65
  }
55
66
  return { marketplace, npm };
56
67
  }
@@ -73,6 +84,14 @@ async function runPluginCommand(
73
84
  return false;
74
85
  }
75
86
 
87
+ function realPath(path: string): string | undefined {
88
+ try {
89
+ return realpathSync(path);
90
+ } catch {
91
+ return undefined;
92
+ }
93
+ }
94
+
76
95
  export async function syncPlugins(ctx: Ctx): Promise<number> {
77
96
  const { change, clearProgress, echo, progress, verbose, warn } = ctx.services.logger;
78
97
 
@@ -105,6 +124,7 @@ export async function syncPlugins(ctx: Ctx): Promise<number> {
105
124
  } else {
106
125
  echo(`[dry-run] omp install pi-intercom@${piIntercomPin}`);
107
126
  }
127
+ echo(`[dry-run] omp plugin link ${kitPluginDir(ctx.home)}`);
108
128
  return 0;
109
129
  }
110
130
 
@@ -121,7 +141,8 @@ export async function syncPlugins(ctx: Ctx): Promise<number> {
121
141
  installed === undefined
122
142
  ? 0
123
143
  : MARKETPLACE_PLUGIN_IDS.filter((pluginId) => installed.marketplace.has(pluginId)).length +
124
- (piIntercomPin !== "" && installed.npm.has("pi-intercom") ? 1 : 0);
144
+ (piIntercomPin !== "" && installed.npm.has("pi-intercom") ? 1 : 0) +
145
+ (installed.npm.has(KIT_PLUGIN_NAME) ? 1 : 0);
125
146
  let operationsSucceeded = 0;
126
147
 
127
148
  for (const pluginId of MARKETPLACE_PLUGIN_IDS) {
@@ -143,7 +164,7 @@ export async function syncPlugins(ctx: Ctx): Promise<number> {
143
164
  if (piIntercomPin === "") {
144
165
  warn("pi-intercom install skipped because SoT/toolchain.json has no verified pi-intercom pin");
145
166
  } else {
146
- const installedVersion = installed?.npm.get("pi-intercom");
167
+ const installedVersion = installed?.npm.get("pi-intercom")?.version;
147
168
  const present = installedVersion !== undefined;
148
169
  if (installedVersion === piIntercomPin) {
149
170
  verbose(`omp npm plugin pi-intercom already installed at ${piIntercomPin}`);
@@ -160,6 +181,18 @@ export async function syncPlugins(ctx: Ctx): Promise<number> {
160
181
  }
161
182
  }
162
183
 
184
+ // The kit plugin is linked when omp's entry resolves to the kit directory.
185
+ // A refresh never applies: the link always points at the current files.
186
+ const kitDir = kitPluginDir(ctx.home);
187
+ const kitPluginPath = installed?.npm.get(KIT_PLUGIN_NAME)?.path;
188
+ const linkedTarget = kitPluginPath === undefined ? undefined : realPath(kitPluginPath);
189
+ if (linkedTarget !== undefined && linkedTarget === realPath(kitDir)) {
190
+ verbose(`omp kit plugin ${KIT_PLUGIN_NAME} already linked`);
191
+ } else if (await runPluginCommand(ctx, KIT_PLUGIN_NAME, ["plugin", "link", kitDir])) {
192
+ operationsSucceeded++;
193
+ if (installed?.npm.has(KIT_PLUGIN_NAME) !== true) pluginsInstalled++;
194
+ }
195
+
163
196
  if (operationsSucceeded > 0) {
164
197
  change(`omp plugins synced (plugins: ~${operationsSucceeded})`);
165
198
  ctx.nextStepTriggers.ompRestart = true;
@@ -6,10 +6,10 @@
6
6
  * Resolution stays within the environment and filesystem probes so no omp
7
7
  * subcommand runs under ctx.dryRun.
8
8
  *
9
- * Split: file deploy lives in `ompFileDeploy.ts`, the marketplace pass in
10
- * `ompMarketplace.ts`, the plugin pass in `ompPlugins.ts`, and the retired-key
11
- * prune in `ompRemovals.ts`. This module keeps the orchestration plus the
12
- * summary surface.
9
+ * Split: file deploy lives in `ompFileDeploy.ts`, the kit plugin files in
10
+ * `ompKitPlugin.ts`, the marketplace pass in `ompMarketplace.ts`, the plugin
11
+ * pass in `ompPlugins.ts`, and the retired-key prune in `ompRemovals.ts`.
12
+ * This module keeps the orchestration plus the summary surface.
13
13
  */
14
14
  import { isAbsolute, resolve } from "node:path";
15
15
 
@@ -19,6 +19,7 @@ import type { Ctx } from "./index";
19
19
  import { ompPaths } from "./ompPaths";
20
20
  import { mergeOmpConfig, mergeOmpModels } from "./ompYaml";
21
21
  import { ensureDirectory, syncMergedYaml, syncWholeFile } from "./ompFileDeploy";
22
+ import { syncKitPlugin } from "./ompKitPlugin";
22
23
  import { syncMarketplace } from "./ompMarketplace";
23
24
  import { syncPlugins } from "./ompPlugins";
24
25
  import { syncOmpModelRemovals, syncOmpRemovals } from "./ompRemovals";
@@ -79,6 +80,8 @@ export async function ompSync(ctx: Ctx): Promise<OmpState> {
79
80
  "omp intercom configuration already in sync",
80
81
  "omp intercom configuration synced",
81
82
  );
83
+ // The plugin pass links this directory, so the files must exist first.
84
+ syncKitPlugin(ctx);
82
85
 
83
86
  const legacyRegistryFile =
84
87
  paths.dataRoot === paths.configRoot ? undefined : p(paths.configRoot, "marketplaces.json");
@@ -0,0 +1,188 @@
1
+ /**
2
+ * Agent temporary directories. `createScratchDir` makes a private directory
3
+ * under the kit scratch root. `removeTemporaryPath` removes a path only when it
4
+ * is strictly inside an allowed root and no other user can change a directory
5
+ * on its path, so a deny-listed `rm -r` is never needed for cleanup and the
6
+ * home directory and `/` can never be the target.
7
+ */
8
+ import {
9
+ chmodSync,
10
+ lstatSync,
11
+ mkdirSync,
12
+ mkdtempSync,
13
+ realpathSync,
14
+ rmSync,
15
+ statSync,
16
+ } from "node:fs";
17
+ import { dirname, isAbsolute, join, relative } from "node:path";
18
+
19
+ import { p } from "./exec";
20
+
21
+ const LABEL_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
22
+
23
+ export function kitCacheDir(home: string): string {
24
+ return p(home, ".cache", "docks-kit");
25
+ }
26
+
27
+ export function scratchRoot(home: string): string {
28
+ return p(kitCacheDir(home), "scratch");
29
+ }
30
+
31
+ export function createScratchDir(root: string, label: string): string {
32
+ if (!LABEL_PATTERN.test(label)) {
33
+ throw new Error("label must match ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$");
34
+ }
35
+ mkdirSync(root, { recursive: true, mode: 0o700 });
36
+ chmodSync(root, 0o700);
37
+ const directory = mkdtempSync(join(root, `${label}-`));
38
+ chmodSync(directory, 0o700);
39
+ return realpathSync(directory);
40
+ }
41
+
42
+ /** True when `child` is `parent` itself or lies below it. */
43
+ export function isSameOrInside(parent: string, child: string): boolean {
44
+ const path = relative(parent, child);
45
+ return path === "" || (!path.startsWith("..") && !isAbsolute(path));
46
+ }
47
+
48
+ /** True when `child` lies strictly below `parent`. */
49
+ export function isStrictlyInside(parent: string, child: string): boolean {
50
+ const path = relative(parent, child);
51
+ return path !== "" && !path.startsWith("..") && !isAbsolute(path);
52
+ }
53
+
54
+ function realpathOrUndefined(path: string): string | undefined {
55
+ try {
56
+ return realpathSync(path);
57
+ } catch {
58
+ return undefined;
59
+ }
60
+ }
61
+
62
+ const STICKY = 0o1000;
63
+ const GROUP_OR_OTHER_WRITE = 0o022;
64
+
65
+ /** The user and root may own a directory on a trusted path. */
66
+ function isTrustedOwner(uid: number, user: number): boolean {
67
+ return uid === user || uid === 0;
68
+ }
69
+
70
+ /**
71
+ * The first directory from the filesystem root down to the parent of `path`
72
+ * that another user can change, or `undefined`. The user or root must own each
73
+ * directory, and group and others must not write it, except a sticky directory
74
+ * whose next entry on the path the user or root owns: POSIX lets only that
75
+ * entry's owner, the directory owner, or root rename such an entry.
76
+ */
77
+ function untrustedParent(path: string, user: number): string | undefined {
78
+ const chain = [path];
79
+ for (let parent = dirname(path); parent !== chain[0]; parent = dirname(parent)) {
80
+ chain.unshift(parent);
81
+ }
82
+ for (let index = 0; index < chain.length - 1; index++) {
83
+ const directory = lstatSync(chain[index]);
84
+ if (!directory.isDirectory() || !isTrustedOwner(directory.uid, user)) return chain[index];
85
+ if ((directory.mode & GROUP_OR_OTHER_WRITE) === 0) continue;
86
+ const sticky = (directory.mode & STICKY) !== 0;
87
+ if (!sticky || !isTrustedOwner(lstatSync(chain[index + 1]).uid, user)) return chain[index];
88
+ }
89
+ return undefined;
90
+ }
91
+
92
+ /**
93
+ * True when no other user can replace or change `root`: its path is trusted,
94
+ * the user or root owns it, and others cannot write it unless it is sticky.
95
+ * Windows has no POSIX owner bits, so every root passes there.
96
+ */
97
+ function isTrustedRoot(root: string): boolean {
98
+ if (process.getuid === undefined) return true;
99
+ const user = process.getuid();
100
+ const stats = lstatSync(root);
101
+ if (!isTrustedOwner(stats.uid, user)) return false;
102
+ if ((stats.mode & GROUP_OR_OTHER_WRITE) !== 0 && (stats.mode & STICKY) === 0) return false;
103
+ return untrustedParent(root, user) === undefined;
104
+ }
105
+
106
+ export function allowedRemovalRoots(input: {
107
+ readonly home: string;
108
+ readonly scratch: string;
109
+ readonly tmp: string;
110
+ readonly platform: NodeJS.Platform;
111
+ }): ReadonlyArray<string> {
112
+ const candidates = [input.scratch, input.tmp];
113
+ if (input.platform !== "win32") candidates.push("/tmp", "/var/tmp");
114
+ const home = realpathOrUndefined(input.home) ?? input.home;
115
+ const roots: Array<string> = [];
116
+ for (const candidate of candidates) {
117
+ const root = realpathOrUndefined(candidate);
118
+ if (root === undefined || roots.includes(root)) continue;
119
+ if (dirname(root) === root || isSameOrInside(root, home)) continue;
120
+ if (!isTrustedRoot(root)) continue;
121
+ roots.push(root);
122
+ }
123
+ return roots;
124
+ }
125
+
126
+ export type RemovalOutcome =
127
+ | { readonly kind: "removed"; readonly path: string }
128
+ | { readonly kind: "refused"; readonly path: string; readonly reason: string };
129
+
130
+ function errorCode(cause: unknown): string | undefined {
131
+ return cause instanceof Error && "code" in cause && typeof cause.code === "string"
132
+ ? cause.code
133
+ : undefined;
134
+ }
135
+
136
+ function errorMessage(cause: unknown): string {
137
+ return cause instanceof Error ? cause.message : String(cause);
138
+ }
139
+
140
+ /**
141
+ * Remove `operand` when every check passes, in this order: it exists, it is
142
+ * not a symbolic link (also with trailing separators), its real path is
143
+ * strictly inside one root and is no root itself, it does not contain the home
144
+ * directory, the current user owns it, no other user can change a directory on
145
+ * its path, and it is on the same filesystem as its root. The first failed
146
+ * check refuses and deletes nothing.
147
+ */
148
+ export function removeTemporaryPath(
149
+ operand: string,
150
+ roots: ReadonlyArray<string>,
151
+ home: string,
152
+ ): RemovalOutcome {
153
+ const refuse = (reason: string): RemovalOutcome => ({ kind: "refused", path: operand, reason });
154
+ // `lstat` of `link/` follows the link, so check the entry without trailing separators.
155
+ const trailing = process.platform === "win32" ? /[\\/]+$/ : /\/+$/;
156
+ const entry = operand.replace(trailing, "") || operand;
157
+ try {
158
+ if (lstatSync(entry).isSymbolicLink()) return refuse("is a symbolic link");
159
+ } catch (cause) {
160
+ return errorCode(cause) === "ENOENT" ? refuse("does not exist") : refuse(errorMessage(cause));
161
+ }
162
+ try {
163
+ const target = realpathSync(entry);
164
+ const root = roots.includes(target)
165
+ ? undefined
166
+ : roots.find((candidate) => isStrictlyInside(candidate, target));
167
+ if (root === undefined) {
168
+ return refuse("is outside the scratch root, the system temporary directory, and /var/tmp");
169
+ }
170
+ if (isSameOrInside(target, realpathOrUndefined(home) ?? home)) {
171
+ return refuse("contains the home directory");
172
+ }
173
+ const stats = statSync(target);
174
+ if (process.getuid !== undefined) {
175
+ const user = process.getuid();
176
+ if (stats.uid !== user) return refuse("is owned by another user");
177
+ const parent = untrustedParent(target, user);
178
+ if (parent !== undefined) {
179
+ return refuse(`has a parent directory that another user can change: ${parent}`);
180
+ }
181
+ }
182
+ if (stats.dev !== statSync(root).dev) return refuse("is on another filesystem");
183
+ rmSync(target, { recursive: true, force: false });
184
+ return { kind: "removed", path: target };
185
+ } catch (cause) {
186
+ return refuse(errorMessage(cause));
187
+ }
188
+ }