hammerkit 1.26.0 → 1.27.0-next.1

package/dist/file/within-root.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertWithinRoot = exports.findRootEscape = void 0;
+const promises_1 = require("fs/promises");
+const path_1 = require("path");
+/**
+ * Why a path would carry a read or write out of a root that somebody else wrote (a
+ * checkout, a sandbox), or null when it stays inside. A path may not lead out of the
+ * root, and none of its parts that exist may be a symbolic link, since docker, tar
+ * and the file system would follow it wherever it points. A part that doesn't exist
+ * yet is fine, it can't be a link until something makes it.
+ */
+async function findRootEscape(root, path) {
+    const inside = (0, path_1.relative)((0, path_1.resolve)(root), (0, path_1.resolve)(root, path));
+    if (inside === '..' || inside.startsWith(`..${path_1.sep}`) || (0, path_1.isAbsolute)(inside)) {
+        return 'is outside of the source';
+    }
+    if (inside === '') {
+        return null;
+    }
+    let current = (0, path_1.resolve)(root);
+    for (const part of inside.split(path_1.sep)) {
+        current = (0, path_1.join)(current, part);
+        const stats = await (0, promises_1.lstat)(current).catch(() => undefined);
+        if (!stats) {
+            return null;
+        }
+        if (stats.isSymbolicLink()) {
+            return `goes through the symbolic link ${(0, path_1.relative)(root, current).split(path_1.sep).join('/')}`;
+        }
+    }
+    return null;
+}
+exports.findRootEscape = findRootEscape;
+async function assertWithinRoot(root, path, describe) {
+    const escape = await findRootEscape(root, path);
+    if (escape) {
+        throw new Error(`${describe} ${escape}`);
+    }
+}
+exports.assertWithinRoot = assertWithinRoot;
+//# sourceMappingURL=within-root.js.map

package/dist/harness/connect.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getHarnessEnvironment = exports.connectSandbox = exports.harnessOptionsFromEnv = exports.DEFAULT_SHELL_TASK = void 0;
+const get_file_context_1 = require("../file/get-file-context");
+const log_1 = require("../log");
+const work_item_status_1 = require("../planner/work-item-status");
+const host_config_1 = require("../remote/host-config");
+const redact_1 = require("../utils/redact");
+const empty_writable_1 = require("../utils/empty-writable");
+const token_source_1 = require("../remote/token-source");
+const bundle_1 = require("../remote/bundle");
+const sandbox_client_1 = require("./sandbox-client");
+exports.DEFAULT_SHELL_TASK = 'sh';
+// The same settings as variables, for harnesses that load hammerkit as a plugin.
+function harnessOptionsFromEnv(env) {
+    const value = (name) => (env[name] && env[name]?.trim()) || undefined;
+    return {
+        server: value('HAMMERKIT_SERVER'),
+        sandbox: value('HAMMERKIT_SANDBOX'),
+        repo: value('HAMMERKIT_REPO'),
+        ref: value('HAMMERKIT_REF'),
+        build: value('HAMMERKIT_BUILD'),
+        shell: value('HAMMERKIT_SHELL'),
+    };
+}
+exports.harnessOptionsFromEnv = harnessOptionsFromEnv;
+async function connectSandbox(environment, options, log = () => undefined) {
+    const config = await (0, host_config_1.readHostConfig)(environment);
+    const name = options.server ?? config.run.on;
+    if (!name || !(0, host_config_1.hasServer)(config.servers, name)) {
+        throw new Error(options.server
+            ? `server ${options.server} is not registered, add it with: hammerkit remote add ${options.server} <url> --issuer <url>`
+            : 'name a server (HAMMERKIT_SERVER or --server), or set a default with: hammerkit remote use <name>');
+    }
+    if (!options.build) {
+        throw new Error('name the published version of the build file whose tasks run on the sandbox by its hash (HAMMERKIT_BUILD or --build), as hammerkit remote publish printed it');
+    }
+    // a run names exactly the version it runs, there is no name that follows the latest one
+    if (!bundle_1.HASH_PATTERN.test(options.build)) {
+        throw new Error(`${options.build} is not the hash of a published version (sha256:...), name it as hammerkit remote publish printed it (HAMMERKIT_BUILD or --build)`);
+    }
+    const server = config.servers[name];
+    const connection = { url: server.url, ...(0, token_source_1.getTokenSource)(environment, name, server) };
+    let sandbox;
+    if (options.sandbox) {
+        sandbox = await sandbox_client_1.SandboxClient.get(connection, options.sandbox);
+    }
+    else if (options.repo && options.ref) {
+        sandbox = await reuseSandbox(connection, options.repo, options.ref);
+        if (sandbox) {
+            log(`took sandbox ${sandbox.id} of ${sandbox.repo} at ${sandbox.commit} on ${name}, it had no changes`);
+        }
+        else {
+            sandbox = await sandbox_client_1.SandboxClient.create(connection, options.repo, options.ref);
+            log(`created sandbox ${sandbox.id} of ${sandbox.repo} at ${sandbox.commit} on ${name}, ` +
+                `set HAMMERKIT_SANDBOX=${sandbox.id} to come back to it`);
+        }
+    }
+    else {
+        throw new Error('name a sandbox (HAMMERKIT_SANDBOX or --sandbox), or a repository and ref to create one from (HAMMERKIT_REPO and HAMMERKIT_REF, or --repo and --ref)');
+    }
+    return new sandbox_client_1.SandboxClient(connection, sandbox, { hash: options.build, shell: options.shell ?? exports.DEFAULT_SHELL_TASK });
+}
+exports.connectSandbox = connectSandbox;
+// A client that starts with a repository and ref takes a sandbox of the caller's of the same
+// that nobody changed and no run holds, checked out at the ref again, rather than creating
+// one on every start: sandboxes stay until they are deleted, and only a few are allowed.
+async function reuseSandbox(connection, repo, ref) {
+    const build = { hash: '', shell: exports.DEFAULT_SHELL_TASK };
+    for (const candidate of await sandbox_client_1.SandboxClient.list(connection)) {
+        if (candidate.repo !== repo || candidate.ref !== ref || candidate.busy) {
+            continue;
+        }
+        const changes = await new sandbox_client_1.SandboxClient(connection, candidate, build).changes();
+        if (changes.files.length === 0) {
+            return sandbox_client_1.SandboxClient.fetch(connection, candidate.id, ref);
+        }
+    }
+    return undefined;
+}
+// What hammerkit needs of its environment to read the host config and the sign-in, for a
+// harness that loads it as a plugin rather than through the command line.
+function getHarnessEnvironment(cwd = process.cwd()) {
+    const secrets = (0, redact_1.createSecretRegistry)();
+    return {
+        cwd,
+        abortCtrl: new AbortController(),
+        processEnvs: process.env,
+        file: (0, get_file_context_1.getFileContext)(cwd),
+        console: (0, log_1.consoleContext)((0, empty_writable_1.emptyWritable)()),
+        status: (0, work_item_status_1.statusConsole)((0, empty_writable_1.emptyWritable)(), secrets),
+        secrets,
+        stdout: (0, empty_writable_1.emptyWritable)(),
+        stderr: (0, empty_writable_1.emptyWritable)(),
+        stdoutColumns: 80,
+    };
+}
+exports.getHarnessEnvironment = getHarnessEnvironment;
+//# sourceMappingURL=connect.js.map

package/dist/harness/format.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.capOutput = exports.toColonNumbers = exports.formatTree = exports.formatSearch = void 0;
+// Lines as grep tools print them: `path:line: text` for a match, `path-line- text` around
+// one, the file names alone or `path:count`, with a note when the server answered a part.
+function formatSearch(result) {
+    let lines;
+    if (result.output_mode === 'files_with_matches') {
+        lines = result.files ?? [];
+    }
+    else if (result.output_mode === 'count') {
+        lines = (result.counts ?? []).map((count) => `${count.path}:${count.count}`);
+    }
+    else {
+        lines = (result.matches ?? []).map((match) => match.context ? `${match.path}-${match.line}- ${match.text}` : `${match.path}:${match.line}: ${match.text}`);
+    }
+    if (lines.length === 0) {
+        return 'No matches found';
+    }
+    if (result.truncated) {
+        lines.push('', `(${lines.length} of ${result.exact ? '' : 'at least '}${result.total} shown, narrow the search or ask with a higher limit)`);
+    }
+    return lines.join('\n');
+}
+exports.formatSearch = formatSearch;
+// The paths of a listing, a directory with a trailing `/`.
+function formatTree(result, prefix = '') {
+    const lines = result.entries.map((entry) => {
+        const path = prefix && entry.path.startsWith(prefix) ? entry.path.slice(prefix.length) : entry.path;
+        return entry.type === 'directory' ? `${path}/` : path;
+    });
+    if (lines.length === 0) {
+        return 'No files found';
+    }
+    if (result.truncated) {
+        lines.push('', `(${result.entries.length} of ${result.total} shown, narrow the pattern)`);
+    }
+    return lines.join('\n');
+}
+exports.formatTree = formatTree;
+// The server numbers lines like `cat -n` (`     1\tline`); some harnesses print `1: line`.
+function toColonNumbers(content) {
+    return content
+        .split('\n')
+        .map((line) => {
+        const match = /^\s*(\d+)\t(.*)$/s.exec(line);
+        return match ? `${match[1]}: ${match[2]}` : line;
+    })
+        .join('\n');
+}
+exports.toColonNumbers = toColonNumbers;
+// The most of a command's output a tool answers: its first and last lines, up to about 30 KB.
+// One `cat` of a big file or a verbose install would otherwise fill the model's context.
+const HEAD_LINES = 50;
+const TAIL_LINES = 200;
+const MAX_CHARS = 30000;
+/**
+ * The head and the tail of a long output, with a line in between that says how much is cut
+ * and how to read it (`readMore`, for example the run_logs call for the run).
+ */
+function capOutput(output, readMore) {
+    const lines = output.split('\n');
+    if (lines.length <= HEAD_LINES + TAIL_LINES && output.length <= MAX_CHARS) {
+        return output;
+    }
+    const many = lines.length > HEAD_LINES + TAIL_LINES;
+    // the end tells most of how a command went: it gets the larger part
+    const head = (many ? lines.slice(0, HEAD_LINES).join('\n') : output).slice(0, MAX_CHARS / 4);
+    const tail = (many ? lines.slice(-TAIL_LINES).join('\n') : output).slice(-(MAX_CHARS * 3) / 4);
+    return `${head}\n… the output is cut here, it has ${lines.length} lines in all: ${readMore}\n${tail}`;
+}
+exports.capOutput = capOutput;
+//# sourceMappingURL=format.js.map

package/dist/harness/mcp-command.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerMcpCommand = void 0;
+const commander_1 = require("commander");
+const log_1 = require("../log");
+const version_1 = require("../version");
+const connect_1 = require("./connect");
+const mcp_1 = require("./mcp");
+// `hammerkit remote mcp`: a Model Context Protocol server on stdio for one sandbox of a
+// server. It lives under `remote`, which already is a command: a top-level `mcp` would hide a
+// task named `mcp`, since `hammerkit <task>` runs a task. Like the other `remote` commands it
+// needs no build file of its own: the tasks are the published ones.
+function registerMcpCommand(remote, environment, input = process.stdin) {
+    // errors go through the program, like those of the other remote commands: it carries the exit handling
+    const program = remote.parent ?? remote;
+    remote
+        .command('mcp')
+        .description('serve the files, shell and tasks of a sandbox on a server as MCP tools over stdio (experimental)')
+        .addOption(new commander_1.Option('--server <name>', 'registered server (default: hammerkit remote use)').env('HAMMERKIT_SERVER'))
+        .addOption(new commander_1.Option('--sandbox <id>', 'a sandbox of yours on the server').env('HAMMERKIT_SANDBOX'))
+        .addOption(new commander_1.Option('--repo <repo>', 'create a sandbox of this repository').env('HAMMERKIT_REPO'))
+        .addOption(new commander_1.Option('--ref <ref>', 'at this branch').env('HAMMERKIT_REF'))
+        .addOption(new commander_1.Option('--build <hash>', 'hash of the published version of the build file whose tasks run on it').env('HAMMERKIT_BUILD'))
+        .addOption(new commander_1.Option('--shell <task>', 'its task whose last command is a shell, like sh -c')
+        .env('HAMMERKIT_SHELL')
+        .default(connect_1.DEFAULT_SHELL_TASK))
+        .action(async (options) => {
+        try {
+            // stdout carries the protocol only, everything else goes to stderr
+            const log = (line) => environment.stderr.write(`hammerkit remote mcp: ${line}\n`);
+            const sandbox = await (0, connect_1.connectSandbox)(environment, options, log);
+            log(`sandbox ${sandbox.id} of ${sandbox.sandbox.repo} at ${sandbox.sandbox.commit}`);
+            const instructions = `The tools work on hammerkit sandbox ${sandbox.id}, a checkout of ${sandbox.sandbox.repo} at ` +
+                `${sandbox.sandbox.commit} on a server. Paths are relative to its root. bash runs a command as the ` +
+                `task ${sandbox.build.shell} of the published build file ${sandbox.build.hash}, run_task runs its other ` +
+                'tasks; only the files are kept between commands. changes shows what changed since the fetch.';
+            const served = (0, mcp_1.serveMcp)(input, environment.stdout, (0, mcp_1.createMcpTools)(async () => sandbox), {
+                name: 'hammerkit',
+                version: (0, version_1.getVersion)(),
+                instructions,
+            });
+            const stopped = new Promise((resolve) => {
+                if (environment.abortCtrl.signal.aborted) {
+                    resolve();
+                }
+                environment.abortCtrl.signal.addEventListener('abort', () => resolve(), { once: true });
+            });
+            await Promise.race([served, stopped]);
+        }
+        catch (e) {
+            if (e instanceof commander_1.CommanderError) {
+                throw e;
+            }
+            program.error(`Mcp was not successful: ${(0, log_1.getErrorMessage)(e)}`, { exitCode: 1 });
+        }
+    });
+}
+exports.registerMcpCommand = registerMcpCommand;
+//# sourceMappingURL=mcp-command.js.map