podman 0.1.5 → 0.2.0

package/dist/index.js

@@ -1,10 +1,5 @@
 // @bun
-// src/index.ts
-import { execFile, spawn } from "child_process";
-import { createInterface } from "readline";
-import { promisify } from "util";
-
-// src/arg-builder.ts
+// src/lib/arg-builder.ts
 class ArgBuilder {
   args;
   constructor(command) {
@@ -42,7 +37,13 @@ class ArgBuilder {
   }
 }
 
-// src/index.ts
+// src/commands/run.ts
+import { spawn as spawn2 } from "child_process";
+
+// src/lib/spawn.ts
+import { promisify } from "util";
+import { execFile, spawn } from "child_process";
+import { createInterface } from "readline";
 var execFileAsync = promisify(execFile);
 async function execPodman(args) {
   const { stdout } = await execFileAsync("podman", args);
@@ -85,13 +86,6 @@ async function execPodmanStreamingWithStdoutLines(args, onLine) {
     });
   });
 }
-var ProcessOutput;
-((ProcessOutput2) => {
-  ProcessOutput2["Pipe"] = "pipe";
-  ProcessOutput2["Ignore"] = "ignore";
-  ProcessOutput2["Inherit"] = "inherit";
-  ProcessOutput2["Tee"] = "tee";
-})(ProcessOutput ||= {});
 function resolveProcessOutput(mode) {
   switch (mode) {
     case "pipe" /* Pipe */:
@@ -105,159 +99,8 @@ function resolveProcessOutput(mode) {
       return { stdio: "inherit", tee: false };
   }
 }
-async function startMachine(machineName = "podman-machine-default") {
-  const out = await execPodman(["machine", "list", "--format", "json"]);
-  const machines = JSON.parse(out || "[]");
-  const m = machines.find((x) => x.Name === machineName);
-  if (!m) {
-    throw new Error(`Podman machine "${machineName}" not found in list:
-${machines.map((x) => `- ${x.Name}`).join(`
-`)}`);
-  }
-  if (m.Running) {
-    return false;
-  }
-  await execPodman(["machine", "start", machineName]);
-  return true;
-}
-async function build(options = {}) {
-  const args = new ArgBuilder("build");
-  args.addValues("--add-host", options.addHost);
-  args.addBool("--all-platforms", options.allPlatforms);
-  args.addValues("--annotation", options.annotation);
-  args.addValue("--arch", options.arch);
-  args.addValue("--authfile", options.authfile);
-  args.addValues("--build-arg", options.buildArg);
-  args.addValue("--build-arg-file", options.buildArgFile);
-  args.addValues("--build-context", options.buildContext);
-  args.addValues("--cache-from", options.cacheFrom);
-  args.addValues("--cache-to", options.cacheTo);
-  args.addValue("--cache-ttl", options.cacheTtl);
-  args.addValues("--cap-add", options.capAdd);
-  args.addValues("--cap-drop", options.capDrop);
-  args.addValue("--cert-dir", options.certDir);
-  args.addValue("--cgroup-parent", options.cgroupParent);
-  args.addValue("--cgroupns", options.cgroupns);
-  args.addBool("--compat-volumes", options.compatVolumes);
-  args.addValues("--cpp-flag", options.cppFlag);
-  args.addValue("--cpu-period", options.cpuPeriod);
-  args.addValue("--cpu-quota", options.cpuQuota);
-  args.addValue("--cpu-shares", options.cpuShares);
-  args.addValue("--cpuset-cpus", options.cpusetCpus);
-  args.addValue("--cpuset-mems", options.cpusetMems);
-  args.addBool("--created-annotation", options.createdAnnotation);
-  args.addValue("--creds", options.creds);
-  args.addValues("--decryption-key", options.decryptionKey);
-  args.addValues("--device", options.device);
-  args.addBool("--disable-compression", options.disableCompression);
-  args.addValue("--dns", options.dns);
-  args.addValues("--dns-option", options.dnsOption);
-  args.addValues("--dns-search", options.dnsSearch);
-  args.addValues("--env", options.env);
-  args.addValue("--file", options.file);
-  args.addBool("--force-rm", options.forceRm);
-  args.addValue("--format", options.format);
-  args.addValue("--from", options.from);
-  args.addValues("--group-add", options.groupAdd);
-  args.addValues("--hooks-dir", options.hooksDir);
-  args.addBool("--http-proxy", options.httpProxy);
-  args.addBool("--identity-label", options.identityLabel);
-  args.addValue("--ignorefile", options.ignorefile);
-  args.addValue("--iidfile", options.iidfile);
-  args.addBool("--inherit-annotations", options.inheritAnnotations);
-  args.addBool("--inherit-labels", options.inheritLabels);
-  args.addValue("--ipc", options.ipc);
-  args.addValue("--isolation", options.isolation);
-  args.addValue("--jobs", options.jobs);
-  args.addValues("--label", options.label);
-  args.addValues("--layer-label", options.layerLabel);
-  args.addBool("--layers", options.layers);
-  args.addValue("--logfile", options.logfile);
-  args.addValue("--manifest", options.manifest);
-  args.addValue("--memory", options.memory);
-  args.addValue("--memory-swap", options.memorySwap);
-  args.addValue("--network", options.network);
-  args.addBool("--no-cache", options.noCache);
-  args.addBool("--no-hostname", options.noHostname);
-  args.addBool("--no-hosts", options.noHosts);
-  args.addBool("--omit-history", options.omitHistory);
-  args.addValue("--os", options.os);
-  args.addValue("--os-feature", options.osFeature);
-  args.addValue("--os-version", options.osVersion);
-  args.addValue("--pid", options.pid);
-  args.addValue("--platform", options.platform);
-  args.addValue("--pull", options.pull);
-  args.addBool("--quiet", options.quiet);
-  args.addValue("--retry", options.retry);
-  args.addValue("--retry-delay", options.retryDelay);
-  args.addBool("--rewrite-timestamp", options.rewriteTimestamp);
-  args.addBool("--rm", options.rm);
-  args.addValues("--runtime-flag", options.runtimeFlag);
-  args.addValue("--sbom", options.sbom);
-  args.addValue("--sbom-image-output", options.sbomImageOutput);
-  args.addValue("--sbom-image-purl-output", options.sbomImagePurlOutput);
-  args.addValue("--sbom-merge-strategy", options.sbomMergeStrategy);
-  args.addValue("--sbom-output", options.sbomOutput);
-  args.addValue("--sbom-purl-output", options.sbomPurlOutput);
-  args.addValue("--sbom-scanner-command", options.sbomScannerCommand);
-  args.addValue("--sbom-scanner-image", options.sbomScannerImage);
-  args.addValues("--secret", options.secret);
-  args.addValues("--security-opt", options.securityOpt);
-  args.addValue("--shm-size", options.shmSize);
-  args.addBool("--skip-unused-stages", options.skipUnusedStages);
-  args.addValue("--source-date-epoch", options.sourceDateEpoch);
-  args.addBool("--squash", options.squash);
-  args.addBool("--squash-all", options.squashAll);
-  args.addValues("--ssh", options.ssh);
-  args.addBool("--stdin", options.stdin);
-  args.addValues("--tag", options.tag);
-  args.addValue("--target", options.target);
-  args.addValue("--timestamp", options.timestamp);
-  args.addValues("--ulimit", options.ulimit);
-  args.addValues("--unsetannotation", options.unsetannotation);
-  args.addValues("--unsetenv", options.unsetenv);
-  args.addValues("--unsetlabel", options.unsetlabel);
-  args.addValue("--userns", options.userns);
-  args.addValue("--userns-gid-map", options.usernsGidMap);
-  args.addValue("--userns-gid-map-group", options.usernsGidMapGroup);
-  args.addValue("--userns-uid-map", options.usernsUidMap);
-  args.addValue("--userns-uid-map-user", options.usernsUidMapUser);
-  args.addValue("--uts", options.uts);
-  args.addValue("--variant", options.variant);
-  args.addValues("--volume", options.volume);
-  args.add(options.context ?? ".");
-  let imageId;
-  await execPodmanStreamingWithStdoutLines(args.toArgs(), (line) => {
-    const trimmed = line.trim();
-    if (/^[a-f0-9]{64}$/.test(trimmed)) {
-      imageId = trimmed;
-    }
-  });
-  if (!imageId) {
-    throw new Error("Unable to determine built image ID from podman output.");
-  }
-  return imageId;
-}
-async function push(options) {
-  const args = new ArgBuilder("push");
-  args.addValue("--authfile", options.authfile);
-  args.addValue("--compression-format", options.compressionFormat);
-  args.addValue("--compression-level", options.compressionLevel);
-  args.addValue("--creds", options.creds);
-  args.addValue("--digestfile", options.digestfile);
-  args.addBool("--disable-content-trust", options.disableContentTrust);
-  args.addBool("--force-compression", options.forceCompression);
-  args.addValue("--format", options.format);
-  args.addBool("--remove-signatures", options.removeSignatures);
-  args.addValue("--retry", options.retry);
-  args.addValue("--retry-delay", options.retryDelay);
-  args.addBool("--tls-verify", options.tlsVerify);
-  args.add(options.image);
-  if (options.destination) {
-    args.add(options.destination);
-  }
-  return execPodmanStreaming(args.toArgs());
-}
+
+// src/commands/run.ts
 function run(options, processOptions = {}) {
   const args = new ArgBuilder("run");
   args.addValues("--add-host", options.addHost);
@@ -416,7 +259,7 @@ function run(options, processOptions = {}) {
   }
   const stdoutConfig = resolveProcessOutput(processOptions.stdout);
   const stderrConfig = resolveProcessOutput(processOptions.stderr);
-  const child = spawn("podman", args.toArgs(), {
+  const child = spawn2("podman", args.toArgs(), {
     stdio: ["inherit", stdoutConfig.stdio, stderrConfig.stdio]
   });
   const stdout = child.stdout ?? null;
@@ -452,10 +295,204 @@ function run(options, processOptions = {}) {
     stderr
   };
 }
+// src/commands/build.ts
+async function build(options = {}) {
+  const args = new ArgBuilder("build");
+  args.addValues("--add-host", options.addHost);
+  args.addBool("--all-platforms", options.allPlatforms);
+  args.addValues("--annotation", options.annotation);
+  args.addValue("--arch", options.arch);
+  args.addValue("--authfile", options.authfile);
+  args.addValues("--build-arg", options.buildArg);
+  args.addValue("--build-arg-file", options.buildArgFile);
+  args.addValues("--build-context", options.buildContext);
+  args.addValues("--cache-from", options.cacheFrom);
+  args.addValues("--cache-to", options.cacheTo);
+  args.addValue("--cache-ttl", options.cacheTtl);
+  args.addValues("--cap-add", options.capAdd);
+  args.addValues("--cap-drop", options.capDrop);
+  args.addValue("--cert-dir", options.certDir);
+  args.addValue("--cgroup-parent", options.cgroupParent);
+  args.addValue("--cgroupns", options.cgroupns);
+  args.addBool("--compat-volumes", options.compatVolumes);
+  args.addValues("--cpp-flag", options.cppFlag);
+  args.addValue("--cpu-period", options.cpuPeriod);
+  args.addValue("--cpu-quota", options.cpuQuota);
+  args.addValue("--cpu-shares", options.cpuShares);
+  args.addValue("--cpuset-cpus", options.cpusetCpus);
+  args.addValue("--cpuset-mems", options.cpusetMems);
+  args.addBool("--created-annotation", options.createdAnnotation);
+  args.addValue("--creds", options.creds);
+  args.addValues("--decryption-key", options.decryptionKey);
+  args.addValues("--device", options.device);
+  args.addBool("--disable-compression", options.disableCompression);
+  args.addValue("--dns", options.dns);
+  args.addValues("--dns-option", options.dnsOption);
+  args.addValues("--dns-search", options.dnsSearch);
+  args.addValues("--env", options.env);
+  args.addValue("--file", options.file);
+  args.addBool("--force-rm", options.forceRm);
+  args.addValue("--format", options.format);
+  args.addValue("--from", options.from);
+  args.addValues("--group-add", options.groupAdd);
+  args.addValues("--hooks-dir", options.hooksDir);
+  args.addBool("--http-proxy", options.httpProxy);
+  args.addBool("--identity-label", options.identityLabel);
+  args.addValue("--ignorefile", options.ignorefile);
+  args.addValue("--iidfile", options.iidfile);
+  args.addBool("--inherit-annotations", options.inheritAnnotations);
+  args.addBool("--inherit-labels", options.inheritLabels);
+  args.addValue("--ipc", options.ipc);
+  args.addValue("--isolation", options.isolation);
+  args.addValue("--jobs", options.jobs);
+  args.addValues("--label", options.label);
+  args.addValues("--layer-label", options.layerLabel);
+  args.addBool("--layers", options.layers);
+  args.addValue("--logfile", options.logfile);
+  args.addValue("--manifest", options.manifest);
+  args.addValue("--memory", options.memory);
+  args.addValue("--memory-swap", options.memorySwap);
+  args.addValue("--network", options.network);
+  args.addBool("--no-cache", options.noCache);
+  args.addBool("--no-hostname", options.noHostname);
+  args.addBool("--no-hosts", options.noHosts);
+  args.addBool("--omit-history", options.omitHistory);
+  args.addValue("--os", options.os);
+  args.addValue("--os-feature", options.osFeature);
+  args.addValue("--os-version", options.osVersion);
+  args.addValue("--pid", options.pid);
+  args.addValue("--platform", options.platform);
+  args.addValue("--pull", options.pull);
+  args.addBool("--quiet", options.quiet);
+  args.addValue("--retry", options.retry);
+  args.addValue("--retry-delay", options.retryDelay);
+  args.addBool("--rewrite-timestamp", options.rewriteTimestamp);
+  args.addBool("--rm", options.rm);
+  args.addValues("--runtime-flag", options.runtimeFlag);
+  args.addValue("--sbom", options.sbom);
+  args.addValue("--sbom-image-output", options.sbomImageOutput);
+  args.addValue("--sbom-image-purl-output", options.sbomImagePurlOutput);
+  args.addValue("--sbom-merge-strategy", options.sbomMergeStrategy);
+  args.addValue("--sbom-output", options.sbomOutput);
+  args.addValue("--sbom-purl-output", options.sbomPurlOutput);
+  args.addValue("--sbom-scanner-command", options.sbomScannerCommand);
+  args.addValue("--sbom-scanner-image", options.sbomScannerImage);
+  args.addValues("--secret", options.secret);
+  args.addValues("--security-opt", options.securityOpt);
+  args.addValue("--shm-size", options.shmSize);
+  args.addBool("--skip-unused-stages", options.skipUnusedStages);
+  args.addValue("--source-date-epoch", options.sourceDateEpoch);
+  args.addBool("--squash", options.squash);
+  args.addBool("--squash-all", options.squashAll);
+  args.addValues("--ssh", options.ssh);
+  args.addBool("--stdin", options.stdin);
+  args.addValues("--tag", options.tag);
+  args.addValue("--target", options.target);
+  args.addValue("--timestamp", options.timestamp);
+  args.addValues("--ulimit", options.ulimit);
+  args.addValues("--unsetannotation", options.unsetannotation);
+  args.addValues("--unsetenv", options.unsetenv);
+  args.addValues("--unsetlabel", options.unsetlabel);
+  args.addValue("--userns", options.userns);
+  args.addValue("--userns-gid-map", options.usernsGidMap);
+  args.addValue("--userns-gid-map-group", options.usernsGidMapGroup);
+  args.addValue("--userns-uid-map", options.usernsUidMap);
+  args.addValue("--userns-uid-map-user", options.usernsUidMapUser);
+  args.addValue("--uts", options.uts);
+  args.addValue("--variant", options.variant);
+  args.addValues("--volume", options.volume);
+  args.add(options.context ?? ".");
+  let imageId;
+  await execPodmanStreamingWithStdoutLines(args.toArgs(), (line) => {
+    const trimmed = line.trim();
+    if (/^[a-f0-9]{64}$/.test(trimmed)) {
+      imageId = trimmed;
+    }
+  });
+  if (!imageId) {
+    throw new Error("Unable to determine built image ID from podman output.");
+  }
+  return imageId;
+}
+// src/commands/push.ts
+async function push(options) {
+  const args = new ArgBuilder("push");
+  args.addValue("--authfile", options.authfile);
+  args.addValue("--compression-format", options.compressionFormat);
+  args.addValue("--compression-level", options.compressionLevel);
+  args.addValue("--creds", options.creds);
+  args.addValue("--digestfile", options.digestfile);
+  args.addBool("--disable-content-trust", options.disableContentTrust);
+  args.addBool("--force-compression", options.forceCompression);
+  args.addValue("--format", options.format);
+  args.addBool("--remove-signatures", options.removeSignatures);
+  args.addValue("--retry", options.retry);
+  args.addValue("--retry-delay", options.retryDelay);
+  args.addBool("--tls-verify", options.tlsVerify);
+  args.add(options.image);
+  if (options.destination) {
+    args.add(options.destination);
+  }
+  return execPodmanStreaming(args.toArgs());
+}
+// src/commands/tag.ts
+async function tag(image, targetNames) {
+  const args = new ArgBuilder("tag");
+  const targets = Array.isArray(targetNames) ? targetNames : [targetNames];
+  if (targets.length === 0) {
+    throw new Error("podman tag requires at least one target name.");
+  }
+  args.add(image);
+  for (const target of targets) {
+    args.add(target);
+  }
+  return execPodmanStreaming(args.toArgs());
+}
+// src/commands/start-machine.ts
+async function listMachines() {
+  const out = await execPodman(["machine", "list", "--format", "json"]);
+  return JSON.parse(out || "[]");
+}
+async function isMachineRunning(machineName = "podman-machine-default") {
+  const machines = await listMachines();
+  const m = machines.find((x) => x.Name === machineName);
+  if (!m) {
+    throw new Error(`Podman machine "${machineName}" not found in list:
+${machines.map((x) => `- ${x.Name}`).join(`
+`)}`);
+  }
+  return m.Running;
+}
+async function startMachine(machineName = "podman-machine-default") {
+  await execPodman(["machine", "start", machineName]);
+}
+async function forceStartMachine(machineName = "podman-machine-default") {
+  try {
+    await startMachine(machineName);
+    return true;
+  } catch (err) {
+    if (isAlreadyRunningError(err)) {
+      return false;
+    }
+    throw err;
+  }
+}
+function isAlreadyRunningError(err) {
+  if (!err || typeof err !== "object") {
+    return false;
+  }
+  const candidate = err;
+  const combined = [candidate.stderr, candidate.stdout, candidate.message].filter(Boolean).join(`
+`);
+  return combined.toLowerCase().includes("already running");
+}
 export {
+  tag,
   startMachine,
   run,
   push,
-  build,
-  ProcessOutput
+  listMachines,
+  isMachineRunning,
+  forceStartMachine,
+  build
 };

package/dist/lib/spawn.d.ts

@@ -0,0 +1,122 @@
+import type { Readable } from 'node:stream';
+export declare function execPodman(args: string[]): Promise<string>;
+export declare function execPodmanStreaming(args: string[]): Promise<void>;
+export declare function execPodmanStreamingWithStdoutLines(args: string[], onLine: (line: string) => void): Promise<void>;
+/**
+ * Output handling strategy for spawned processes.
+ *
+ * @example
+ * ```ts
+ * import {ProcessOutput} from 'podman'
+ *
+ * const mode = ProcessOutput.Tee
+ * ```
+ */
+export declare enum ProcessOutput {
+    /** Capture output in a stream. */
+    Pipe = "pipe",
+    /** Discard output. */
+    Ignore = "ignore",
+    /** Forward output to the parent process. */
+    Inherit = "inherit",
+    /** Capture output and also forward it to the parent process. */
+    Tee = "tee"
+}
+/**
+ * Process output configuration for podman run.
+ *
+ * @example
+ * ```ts
+ * import {ProcessOutput} from 'podman'
+ *
+ * const options = {stdout: ProcessOutput.Tee, stderr: ProcessOutput.Pipe}
+ * ```
+ */
+export type ProcessOptions = {
+    /** How stdout is handled. Defaults to [`ProcessOutput.Inherit`]{@link ProcessOutput.Inherit}. */
+    stdout?: ProcessOutput;
+    /** How stderr is handled. Defaults to [`ProcessOutput.Inherit`]{@link ProcessOutput.Inherit}. */
+    stderr?: ProcessOutput;
+};
+export declare function resolveProcessOutput(mode: ProcessOutput | undefined): ProcessOutputConfig;
+/**
+ * Handle returned by [`run`]{@link run} to control the podman process.
+ *
+ * @example
+ * ```ts
+ * import {run, ProcessOutput} from 'podman'
+ *
+ * const proc = run(
+ *     {image: 'alpine:latest', command: 'echo', commandArgs: ['hello']},
+ *     {stdout: ProcessOutput.Tee},
+ * )
+ * await proc.waitThrow()
+ * ```
+ */
+export type PodmanRunHandle = {
+    /**
+     * Sends SIGKILL to the podman process.
+     *
+     * @returns True if the signal was sent, false otherwise.
+     *
+     * @example
+     * ```ts
+     * import {run} from 'podman'
+     *
+     * const proc = await run({image: 'alpine:latest', command: 'sleep', commandArgs: ['60']})
+     * proc.kill()
+     * ```
+     */
+    kill: () => boolean;
+    /**
+     * Sends SIGTERM to the podman process.
+     *
+     * @returns True if the signal was sent, false otherwise.
+     *
+     * @example
+     * ```ts
+     * import {run} from 'podman'
+     *
+     * const proc = await run({image: 'alpine:latest', command: 'sleep', commandArgs: ['60']})
+     * proc.term()
+     * ```
+     */
+    term: () => boolean;
+    /**
+     * Waits for the podman process to exit.
+     *
+     * @returns Resolves with the exit code of the podman process.
+     *
+     * @example
+     * ```ts
+     * import {run} from 'podman'
+     *
+     * const proc = await run({image: 'alpine:latest', command: 'true'})
+     * const code = await proc.wait()
+     * console.log(code)
+     * ```
+     */
+    wait: () => Promise<number>;
+    /**
+     * Waits for the podman process to exit and rejects on non-zero exit codes.
+     *
+     * @returns Resolves with the exit code when it is zero.
+     *
+     * @example
+     * ```ts
+     * import {run} from 'podman'
+     *
+     * const proc = await run({image: 'alpine:latest', command: 'false'})
+     * await proc.waitThrow()
+     * ```
+     */
+    waitThrow: () => Promise<number>;
+    /** Stdout stream when configured with [`ProcessOutput.Pipe`]{@link ProcessOutput.Pipe} or [`ProcessOutput.Tee`]{@link ProcessOutput.Tee}. */
+    stdout: Readable | null;
+    /** Stderr stream when configured with [`ProcessOutput.Pipe`]{@link ProcessOutput.Pipe} or [`ProcessOutput.Tee`]{@link ProcessOutput.Tee}. */
+    stderr: Readable | null;
+};
+export type ProcessOutputConfig = {
+    stdio: 'pipe' | 'ignore' | 'inherit';
+    tee: boolean;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "podman",
-    "version": "0.1.5",
+    "version": "0.2.0",
     "description": "Utilities for starting a Podman machine from Bun/Node.",
     "author": "Mark Penner <npm@mpen.ca>",
     "module": "index.ts",