impel-cli 0.18.17 → 0.19.0

package/src/remote/aws.js

@@ -0,0 +1,142 @@
+import { runCapture, runInteractive, sleep } from "./process.js";
+
+function awsPrefix({ region, profile }) {
+  return [
+    ...(region ? ["--region", region] : []),
+    ...(profile ? ["--profile", profile] : []),
+  ];
+}
+
+function awsJson(context, args) {
+  const result = runCapture(process.env.IMPEL_REMOTE_AWS_BIN || "aws", [...awsPrefix(context), ...args, "--output", "json"]);
+  try {
+    return JSON.parse(result.stdout);
+  } catch {
+    throw new Error(`AWS CLI returned invalid JSON for ${args.slice(0, 2).join(" ")}`);
+  }
+}
+
+export function readStack(context) {
+  const payload = awsJson(context, ["cloudformation", "describe-stacks", "--stack-name", context.stackName]);
+  const stack = payload?.Stacks?.[0];
+  if (!stack || !Array.isArray(stack.Outputs)) throw new Error(`CloudFormation stack ${context.stackName} has no outputs`);
+  const outputs = Object.fromEntries(stack.Outputs.map((entry) => [entry.OutputKey, entry.OutputValue]));
+  for (const name of ["ClusterName", "TaskDefinitionArn", "PublicSubnetIds", "RunnerSecurityGroupId"]) {
+    if (!outputs[name]) throw new Error(`CloudFormation stack ${context.stackName} is missing output ${name}`);
+  }
+  return outputs;
+}
+
+export function startTask(context, { outputs, publicKey, ttlSeconds, runId }) {
+  const networkConfiguration = JSON.stringify({
+    awsvpcConfiguration: {
+      subnets: outputs.PublicSubnetIds.split(",").filter(Boolean),
+      securityGroups: [outputs.RunnerSecurityGroupId],
+      assignPublicIp: "ENABLED",
+    },
+  });
+  const overrides = JSON.stringify({
+    containerOverrides: [{
+      name: "runner",
+      environment: [
+        { name: "IMPEL_REMOTE_SSH_PUBLIC_KEY", value: publicKey.trim() },
+        { name: "IMPEL_REMOTE_TTL_SECONDS", value: String(ttlSeconds) },
+        { name: "IMPEL_REMOTE_RUN_ID", value: runId },
+      ],
+    }],
+  });
+  const payload = awsJson(context, [
+    "ecs", "run-task",
+    "--cluster", outputs.ClusterName,
+    "--task-definition", outputs.TaskDefinitionArn,
+    "--launch-type", "FARGATE",
+    "--platform-version", "LATEST",
+    "--enable-execute-command",
+    "--network-configuration", networkConfiguration,
+    "--overrides", overrides,
+    "--tags", `key=useimpel:purpose,value=remote-session`, `key=useimpel:run-id,value=${runId}`,
+  ]);
+  const task = payload?.tasks?.[0];
+  if (!task?.taskArn) {
+    const reason = payload?.failures?.[0]?.reason || "ECS returned no task";
+    throw new Error(`could not start remote runner: ${reason}`);
+  }
+  return { taskArn: task.taskArn, clusterName: outputs.ClusterName };
+}
+
+export function describeTask(context, state) {
+  const payload = awsJson(context, [
+    "ecs", "describe-tasks",
+    "--cluster", state.aws.clusterName,
+    "--tasks", state.aws.taskArn,
+  ]);
+  const task = payload?.tasks?.[0];
+  if (!task) throw new Error(`ECS task ${state.aws.taskArn} was not found`);
+  const container = task.containers?.find((candidate) => candidate.name === "runner") || task.containers?.[0] || {};
+  const executeAgent = container.managedAgents?.find((candidate) => candidate.name === "ExecuteCommandAgent");
+  const taskId = String(state.aws.taskArn).split("/").at(-1);
+  return {
+    lastStatus: task.lastStatus || "UNKNOWN",
+    desiredStatus: task.desiredStatus || "UNKNOWN",
+    stoppedReason: task.stoppedReason || null,
+    exitCode: Number.isInteger(container.exitCode) ? container.exitCode : null,
+    containerReason: container.reason || null,
+    runtimeId: container.runtimeId || null,
+    executeAgentStatus: executeAgent?.lastStatus || null,
+    taskId,
+    ssmTarget: container.runtimeId
+      ? `ecs:${state.aws.clusterName}_${taskId}_${container.runtimeId}`
+      : null,
+  };
+}
+
+export async function waitForTaskReady(context, state, timeoutSeconds) {
+  const deadline = Date.now() + timeoutSeconds * 1000;
+  let latest;
+  while (Date.now() < deadline) {
+    latest = describeTask(context, state);
+    if (
+      latest.lastStatus === "RUNNING"
+      && latest.executeAgentStatus === "RUNNING"
+      && latest.runtimeId
+    ) return latest;
+    if (latest.lastStatus === "STOPPED") {
+      throw new Error(`remote runner stopped during startup: ${latest.stoppedReason || latest.containerReason || `exit ${latest.exitCode ?? "unknown"}`}`);
+    }
+    await sleep(Number(process.env.IMPEL_REMOTE_POLL_MS || 3000));
+  }
+  throw new Error(`remote runner did not become ready within ${timeoutSeconds} seconds`);
+}
+
+export function stopTask(context, state, reason = "Impel remote session stopped") {
+  if (!state?.aws?.taskArn || !state?.aws?.clusterName) return false;
+  runCapture(process.env.IMPEL_REMOTE_AWS_BIN || "aws", [
+    ...awsPrefix(context),
+    "ecs", "stop-task",
+    "--cluster", state.aws.clusterName,
+    "--task", state.aws.taskArn,
+    "--reason", reason,
+    "--output", "json",
+  ]);
+  return true;
+}
+
+export function startSshProxy(context, state, port) {
+  const target = state?.aws?.ssmTarget;
+  if (!target) throw new Error(`remote run ${state.runId} has no ready SSM target`);
+  return runInteractive(process.env.IMPEL_REMOTE_AWS_BIN || "aws", [
+    ...awsPrefix(context),
+    "ssm", "start-session",
+    "--target", target,
+    "--document-name", "AWS-StartSSHSession",
+    "--parameters", `portNumber=${port}`,
+  ], { allowFailure: true });
+}
+
+export function awsContext(stateOrOptions) {
+  return {
+    region: stateOrOptions?.region || stateOrOptions?.aws?.region || "eu-west-2",
+    profile: stateOrOptions?.profile || stateOrOptions?.aws?.profile || null,
+    stackName: stateOrOptions?.stackName || stateOrOptions?.aws?.stackName || "impel-remote-dev",
+  };
+}

package/src/remote/process.js

@@ -0,0 +1,131 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+import { redactSecretText } from "../config.js";
+
+const DEFAULT_MAX_BUFFER = 64 * 1024 * 1024;
+
+export class RemoteProcessError extends Error {
+  constructor(command, args, result) {
+    const rendered = [command, ...args].map((value) => JSON.stringify(String(value))).join(" ");
+    const detail = redactSecretText(result?.stderr || result?.error?.message || "command failed").trim();
+    super(`${rendered} failed${detail ? `: ${detail}` : ""}`);
+    this.command = command;
+    this.args = [...args];
+    this.status = Number.isInteger(result?.status) ? result.status : 1;
+  }
+}
+
+export function findExecutable(command, environment = process.env) {
+  if (path.isAbsolute(command)) {
+    try {
+      fs.accessSync(command, fs.constants.X_OK);
+      return command;
+    } catch {
+      return null;
+    }
+  }
+  const pathValue = environment.PATH || "";
+  for (const directory of pathValue.split(path.delimiter)) {
+    if (!directory) continue;
+    const candidate = path.join(directory, command);
+    try {
+      fs.accessSync(candidate, fs.constants.X_OK);
+      return candidate;
+    } catch {
+      // Keep searching PATH.
+    }
+  }
+  return null;
+}
+
+export function requireExecutables(commands, environment = process.env) {
+  const missing = commands.filter((command) => !findExecutable(command, environment));
+  if (missing.length > 0) {
+    throw new Error(`required command${missing.length === 1 ? " is" : "s are"} not installed: ${missing.join(", ")}`);
+  }
+}
+
+export function runCapture(command, args = [], {
+  cwd,
+  env = process.env,
+  input,
+  maxBuffer = DEFAULT_MAX_BUFFER,
+  allowFailure = false,
+} = {}) {
+  const result = spawnSync(command, args, {
+    cwd,
+    env,
+    input,
+    encoding: "utf8",
+    maxBuffer,
+    windowsHide: true,
+  });
+  if (!allowFailure && (result.error || result.status !== 0)) {
+    throw new RemoteProcessError(command, args, result);
+  }
+  return {
+    status: Number.isInteger(result.status) ? result.status : 1,
+    stdout: result.stdout || "",
+    stderr: result.stderr || "",
+    error: result.error || null,
+  };
+}
+
+export function runBuffer(command, args = [], {
+  cwd,
+  env = process.env,
+  input,
+  maxBuffer = DEFAULT_MAX_BUFFER,
+  allowFailure = false,
+} = {}) {
+  const result = spawnSync(command, args, {
+    cwd,
+    env,
+    input,
+    encoding: null,
+    maxBuffer,
+    windowsHide: true,
+  });
+  if (!allowFailure && (result.error || result.status !== 0)) {
+    throw new RemoteProcessError(command, args, {
+      ...result,
+      stderr: result.stderr?.toString("utf8") || "",
+    });
+  }
+  return {
+    status: Number.isInteger(result.status) ? result.status : 1,
+    stdout: result.stdout || Buffer.alloc(0),
+    stderr: result.stderr || Buffer.alloc(0),
+    error: result.error || null,
+  };
+}
+
+export function runInteractive(command, args = [], {
+  cwd,
+  env = process.env,
+  inputFile,
+  allowFailure = false,
+} = {}) {
+  let descriptor;
+  try {
+    if (inputFile) descriptor = fs.openSync(inputFile, "r");
+    const result = spawnSync(command, args, {
+      cwd,
+      env,
+      stdio: [descriptor ?? "inherit", "inherit", "inherit"],
+      windowsHide: false,
+    });
+    if (!allowFailure && (result.error || result.status !== 0)) {
+      throw new RemoteProcessError(command, args, result);
+    }
+    return Number.isInteger(result.status) ? result.status : 1;
+  } finally {
+    if (descriptor !== undefined) fs.closeSync(descriptor);
+  }
+}
+
+export function sleep(milliseconds) {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}

package/src/remote/state.js

@@ -0,0 +1,202 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { CONFIG_DIR } from "../config.js";
+import { IMPEL_CLI_ENTRYPOINT } from "../selfInvocation.js";
+import { renameWithWindowsRetry } from "../windowsFs.js";
+
+export const REMOTE_STATE_VERSION = 1;
+export const REMOTE_ROOT = process.env.IMPEL_REMOTE_STATE_DIR || path.join(CONFIG_DIR, "remote");
+export const REMOTE_RUNS_DIR = path.join(REMOTE_ROOT, "runs");
+export const SSH_CONFIG_PATH = process.env.IMPEL_REMOTE_SSH_CONFIG || path.join(os.homedir(), ".ssh", "config");
+
+const RUN_ID_RE = /^run_[a-z0-9]{16}$/u;
+const SSH_START_PREFIX = "# >>> impel remote ";
+const SSH_END_PREFIX = "# <<< impel remote ";
+
+function lstatOrNull(target) {
+  try {
+    return fs.lstatSync(target);
+  } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+function ensurePrivateDirectory(directory) {
+  const existing = lstatOrNull(directory);
+  if (existing?.isSymbolicLink()) throw new Error(`${directory} must not be a symbolic link`);
+  if (existing && !existing.isDirectory()) throw new Error(`${directory} must be a directory`);
+  fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+  try { fs.chmodSync(directory, 0o700); } catch { /* Best effort on Windows. */ }
+}
+
+function atomicWrite(filePath, contents, mode = 0o600) {
+  ensurePrivateDirectory(path.dirname(filePath));
+  const existing = lstatOrNull(filePath);
+  if (existing?.isSymbolicLink()) throw new Error(`${filePath} must not be a symbolic link`);
+  if (existing && !existing.isFile()) throw new Error(`${filePath} must be a regular file`);
+  const temporaryPath = `${filePath}.tmp-${process.pid}-${crypto.randomUUID()}`;
+  try {
+    fs.writeFileSync(temporaryPath, contents, { mode });
+    renameWithWindowsRetry(temporaryPath, filePath);
+    try { fs.chmodSync(filePath, mode); } catch { /* Best effort on Windows. */ }
+  } finally {
+    try { fs.rmSync(temporaryPath, { force: true }); } catch { /* Rename removed it. */ }
+  }
+}
+
+export function newRunId() {
+  return `run_${crypto.randomBytes(10).toString("hex").slice(0, 16)}`;
+}
+
+export function validateRunId(runId) {
+  const normalized = String(runId || "").trim();
+  if (!RUN_ID_RE.test(normalized)) throw new Error(`invalid remote run id ${JSON.stringify(normalized)}`);
+  return normalized;
+}
+
+export function runDirectory(runId) {
+  return path.join(REMOTE_RUNS_DIR, validateRunId(runId));
+}
+
+export function runPaths(runId) {
+  const root = runDirectory(runId);
+  return {
+    root,
+    state: path.join(root, "run.json"),
+    privateKey: path.join(root, "id_ed25519"),
+    publicKey: path.join(root, "id_ed25519.pub"),
+    knownHosts: path.join(root, "known_hosts"),
+    bundle: path.join(root, "repo.bundle"),
+    fileList: path.join(root, "files.list"),
+    archive: path.join(root, "working-tree.tar"),
+    deletedList: path.join(root, "deleted.list"),
+  };
+}
+
+export function initializeRun(runId) {
+  const paths = runPaths(runId);
+  ensurePrivateDirectory(paths.root);
+  return paths;
+}
+
+export function writeRunState(state) {
+  const runId = validateRunId(state?.runId);
+  const next = { ...state, schemaVersion: REMOTE_STATE_VERSION, updatedAt: new Date().toISOString() };
+  atomicWrite(runPaths(runId).state, `${JSON.stringify(next, null, 2)}\n`);
+  return next;
+}
+
+export function readRunState(runId) {
+  const statePath = runPaths(runId).state;
+  let value;
+  try {
+    value = JSON.parse(fs.readFileSync(statePath, "utf8"));
+  } catch (error) {
+    if (error?.code === "ENOENT") throw new Error(`remote run ${runId} does not exist`);
+    throw new Error(`${statePath} is not a valid remote run state file`);
+  }
+  if (value?.schemaVersion !== REMOTE_STATE_VERSION || value?.runId !== runId) {
+    throw new Error(`${statePath} has an unsupported remote run state version`);
+  }
+  return value;
+}
+
+export function listRunStates() {
+  let entries;
+  try {
+    entries = fs.readdirSync(REMOTE_RUNS_DIR, { withFileTypes: true });
+  } catch (error) {
+    if (error?.code === "ENOENT") return [];
+    throw error;
+  }
+  const states = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory() || !RUN_ID_RE.test(entry.name)) continue;
+    try { states.push(readRunState(entry.name)); } catch { /* A corrupt run is not selected implicitly. */ }
+  }
+  return states.sort((left, right) => String(right.createdAt).localeCompare(String(left.createdAt)));
+}
+
+export function resolveRunId(requested, { includeStopped = false } = {}) {
+  if (requested) return validateRunId(requested);
+  const current = listRunStates().find((state) => includeStopped || state.status !== "stopped");
+  if (!current) throw new Error("no active remote run found; start one with `impel remote up`");
+  return current.runId;
+}
+
+export function sshAlias(runId) {
+  return `impel-${validateRunId(runId).replaceAll("_", "-")}`;
+}
+
+function sshQuote(value) {
+  const text = String(value);
+  if (/[\r\n\0]/u.test(text)) throw new Error("unsafe value in managed SSH configuration");
+  return `"${text.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
+}
+
+function removeManagedBlock(text, runId) {
+  const startMarker = `${SSH_START_PREFIX}${runId} >>>`;
+  const endMarker = `${SSH_END_PREFIX}${runId} <<<`;
+  const start = text.indexOf(startMarker);
+  if (start === -1) return text;
+  const end = text.indexOf(endMarker, start + startMarker.length);
+  if (end === -1) throw new Error(`${SSH_CONFIG_PATH} has an incomplete Impel remote block for ${runId}`);
+  const after = end + endMarker.length;
+  return `${text.slice(0, start).trimEnd()}${text.slice(after).trimStart() ? `\n${text.slice(after).trimStart()}` : ""}`;
+}
+
+export function installSshAlias(state) {
+  const { runId } = state;
+  const paths = runPaths(runId);
+  const alias = state.alias || sshAlias(runId);
+  const current = fs.existsSync(SSH_CONFIG_PATH) ? fs.readFileSync(SSH_CONFIG_PATH, "utf8") : "";
+  const preserved = removeManagedBlock(current, runId).trimEnd();
+  const proxyTokens = [process.execPath, IMPEL_CLI_ENTRYPOINT, "remote", "proxy", runId, "--port", "%p"];
+  const block = [
+    `${SSH_START_PREFIX}${runId} >>>`,
+    `Host ${alias}`,
+    `  HostName ${runId}.remote.impel.invalid`,
+    "  User agent",
+    "  Port 22",
+    `  IdentityFile ${sshQuote(paths.privateKey)}`,
+    "  IdentitiesOnly yes",
+    "  BatchMode yes",
+    "  StrictHostKeyChecking accept-new",
+    `  UserKnownHostsFile ${sshQuote(paths.knownHosts)}`,
+    `  ProxyCommand ${proxyTokens.map(sshQuote).join(" ")}`,
+    `${SSH_END_PREFIX}${runId} <<<`,
+  ].join("\n");
+  // OpenSSH keeps the first value it obtains for most settings. Put concrete
+  // Impel hosts before user wildcard blocks so a preceding `Host *` cannot
+  // replace this run's user, hostname, key, or ProxyCommand.
+  atomicWrite(SSH_CONFIG_PATH, `${block}${preserved ? `\n\n${preserved}` : ""}\n`);
+  return alias;
+}
+
+export function removeSshAlias(runId) {
+  if (!fs.existsSync(SSH_CONFIG_PATH)) return false;
+  const current = fs.readFileSync(SSH_CONFIG_PATH, "utf8");
+  const next = removeManagedBlock(current, validateRunId(runId));
+  if (next === current) return false;
+  atomicWrite(SSH_CONFIG_PATH, next.trim() ? `${next.trimEnd()}\n` : "");
+  return true;
+}
+
+export function removeRunSecrets(runId) {
+  const paths = runPaths(runId);
+  for (const target of [
+    paths.privateKey,
+    paths.publicKey,
+    paths.knownHosts,
+    paths.bundle,
+    paths.fileList,
+    paths.archive,
+    paths.deletedList,
+  ]) {
+    try { fs.rmSync(target, { force: true }); } catch { /* Best-effort local cleanup. */ }
+  }
+}