@wpelevator/tug 0.2.1 → 0.4.0

package/dist/archive.js

@@ -3,7 +3,9 @@ import * as tar from 'tar';
 export async function scanArchive(file, inspect) {
     await new Promise((resolve, reject) => {
         const input = createReadStream(file);
-        const parser = new tar.Parser({ strict: true, onReadEntry(entry) {
+        const parser = new tar.Parser({
+            strict: true,
+            onReadEntry(entry) {
                 try {
                     inspect(entry);
                     entry.resume();
@@ -11,9 +13,13 @@ export async function scanArchive(file, inspect) {
                 catch (error) {
                     parser.abort(error);
                 }
-            } });
+            },
+        });
         input.once('error', reject);
-        parser.once('error', error => { input.destroy(); reject(error); });
+        parser.once('error', (error) => {
+            input.destroy();
+            reject(error);
+        });
         parser.once('end', resolve);
         input.pipe(parser);
     });

package/dist/artifacts.js

@@ -26,10 +26,18 @@ export async function hashArchive(file) {
 export async function saveImageArchive(imageRef, file) {
     const child = spawn('docker', ['save', imageRef], { stdio: ['ignore', 'pipe', 'pipe'] });
     let error = '';
-    child.stderr.on('data', chunk => { error = (error + chunk).slice(-4000); });
-    const finished = new Promise((resolve, reject) => { child.once('error', reject); child.once('close', code => code === 0 ? resolve() : reject(new Error(`docker save failed (${code}): ${error}`))); });
+    child.stderr.on('data', (chunk) => {
+        error = (error + chunk).slice(-4000);
+    });
+    const finished = new Promise((resolve, reject) => {
+        child.once('error', reject);
+        child.once('close', (code) => code === 0 ? resolve() : reject(new Error(`docker save failed (${code}): ${error}`)));
+    });
     try {
-        await Promise.all([pipeline(child.stdout, createGzip(), createWriteStream(file, { mode: 0o600 })), finished]);
+        await Promise.all([
+            pipeline(child.stdout, createGzip(), createWriteStream(file, { mode: 0o600 })),
+            finished,
+        ]);
     }
     catch (e) {
         child.kill();
@@ -53,11 +61,14 @@ export async function validateImageArchive(file, expectedRef, maxExpandedBytes =
     let manifestBytes;
     let indexBytes;
     let repositoriesBytes;
-    await scanArchive(file, entry => {
+    await scanArchive(file, (entry) => {
         const name = entry.path.replace(/^\.\//, '');
         if (++entries > 100000 || (expanded += entry.size) > maxExpandedBytes)
             invalid = 'image archive exceeds expanded limits';
-        if (name.startsWith('/') || name.split('/').includes('..') || !['File', 'Directory'].includes(entry.type) || names.has(name))
+        if (name.startsWith('/') ||
+            name.split('/').includes('..') ||
+            !['File', 'Directory'].includes(entry.type) ||
+            names.has(name))
             invalid = 'unsafe image archive entry';
         if (invalid)
             throw new Error(invalid);
@@ -86,42 +97,53 @@ export async function validateImageArchive(file, expectedRef, maxExpandedBytes =
                         chunks.push(Buffer.from(chunk));
                 }
             });
-            entry.on('end', () => { blobHashes.set(name, hash.digest('hex')); if (json)
-                blobMetadata.set(name, Buffer.concat(chunks)); });
+            entry.on('end', () => {
+                blobHashes.set(name, hash.digest('hex'));
+                if (json)
+                    blobMetadata.set(name, Buffer.concat(chunks));
+            });
         }
         if (['manifest.json', 'index.json', 'repositories'].includes(name) && !invalid) {
             if (entry.size > 1024 ** 2) {
                 throw new Error('image manifest exceeds limit');
             }
             const chunks = [];
-            entry.on('data', chunk => chunks.push(Buffer.from(chunk)));
-            entry.on('end', () => { const value = Buffer.concat(chunks); if (name === 'manifest.json')
-                manifestBytes = value;
-            else if (name === 'index.json')
-                indexBytes = value;
-            else
-                repositoriesBytes = value; });
+            entry.on('data', (chunk) => chunks.push(Buffer.from(chunk)));
+            entry.on('end', () => {
+                const value = Buffer.concat(chunks);
+                if (name === 'manifest.json')
+                    manifestBytes = value;
+                else if (name === 'index.json')
+                    indexBytes = value;
+                else
+                    repositoriesBytes = value;
+            });
         }
     });
     if (invalid)
         throw new Error(invalid);
     const manifest = JSON.parse(manifestBytes?.toString() || 'null');
-    if (!Array.isArray(manifest) || manifest.length !== 1 || JSON.stringify(manifest[0].RepoTags) !== JSON.stringify([expectedRef]))
+    if (!Array.isArray(manifest) ||
+        manifest.length !== 1 ||
+        JSON.stringify(manifest[0].RepoTags) !== JSON.stringify([expectedRef]))
         throw new Error('archive must contain exactly the declared Tug image tag');
     if (typeof manifest[0].Config !== 'string' || !regular.has(manifest[0].Config))
         throw new Error('image archive is missing its configuration');
-    if (!Array.isArray(manifest[0].Layers) || manifest[0].Layers.some((layer) => typeof layer !== 'string' || !regular.has(layer)))
+    if (!Array.isArray(manifest[0].Layers) ||
+        manifest[0].Layers.some((layer) => typeof layer !== 'string' || !regular.has(layer)))
         throw new Error('image archive is missing layers');
     let configBytes;
-    await scanArchive(file, entry => {
+    await scanArchive(file, (entry) => {
         if (entry.path.replace(/^\.\//, '') !== manifest[0].Config)
             return;
         if (entry.size > 4 * 1024 ** 2) {
             throw new Error('image configuration exceeds limit');
         }
         const chunks = [];
-        entry.on('data', chunk => chunks.push(Buffer.from(chunk)));
-        entry.on('end', () => { configBytes = Buffer.concat(chunks); });
+        entry.on('data', (chunk) => chunks.push(Buffer.from(chunk)));
+        entry.on('end', () => {
+            configBytes = Buffer.concat(chunks);
+        });
     });
     if (invalid)
         throw new Error(invalid);
@@ -131,8 +153,17 @@ export async function validateImageArchive(file, expectedRef, maxExpandedBytes =
         const index = JSON.parse(indexBytes.toString());
         const descriptor = index.manifests?.[0];
         const annotations = descriptor?.annotations || {};
-        const allowedNames = new Set([expectedRef, `docker.io/${expectedRef}`, ...(!expectedRef.includes('/') ? [`docker.io/library/${expectedRef}`] : [])]);
-        if (!Array.isArray(index.manifests) || index.manifests.length < 1 || !allowedNames.has(annotations['io.containerd.image.name']) || (annotations['org.opencontainers.image.ref.name'] && !allowedNames.has(annotations['org.opencontainers.image.ref.name']) && annotations['org.opencontainers.image.ref.name'] !== expectedRef.split(':').at(-1)))
+        const allowedNames = new Set([
+            expectedRef,
+            `docker.io/${expectedRef}`,
+            ...(!expectedRef.includes('/') ? [`docker.io/library/${expectedRef}`] : []),
+        ]);
+        if (!Array.isArray(index.manifests) ||
+            index.manifests.length < 1 ||
+            !allowedNames.has(annotations['io.containerd.image.name']) ||
+            (annotations['org.opencontainers.image.ref.name'] &&
+                !allowedNames.has(annotations['org.opencontainers.image.ref.name']) &&
+                annotations['org.opencontainers.image.ref.name'] !== expectedRef.split(':').at(-1)))
             throw new Error('OCI index contains unexpected image names');
         const expectedConfig = `sha256:${createHash('sha256').update(configBytes).digest('hex')}`;
         const expectedLayers = manifest[0].Layers;
@@ -147,15 +178,21 @@ export async function validateImageArchive(file, expectedRef, maxExpandedBytes =
                 throw new Error('OCI metadata content digest mismatch or missing blob');
             return JSON.parse(bytes.toString());
         };
-        const isAttestationDocument = (document, imageConfig) => (Object.keys(imageConfig).length === 0 && document.artifactType === 'application/vnd.docker.attestation.manifest.v1+json') || (imageConfig.os === 'unknown' && imageConfig.architecture === 'unknown');
+        const isAttestationDocument = (document, imageConfig) => (Object.keys(imageConfig).length === 0 &&
+            document.artifactType === 'application/vnd.docker.attestation.manifest.v1+json') ||
+            (imageConfig.os === 'unknown' && imageConfig.architecture === 'unknown');
         /** An attestation is acceptable only when it describes this exact saved image and carries nothing but in-toto statements. */
         const verifyAttestation = (document, subject) => {
-            const subjectConfig = subject ? readBlob(subject).config : undefined;
+            const subjectConfig = subject
+                ? readBlob(subject).config
+                : undefined;
             if (subjectConfig?.digest !== expectedConfig)
                 throw new Error('attestation subject does not match saved image');
             for (const layer of document.layers) {
                 const name = `blobs/sha256/${layer.digest?.slice(7)}`;
-                if (layer.mediaType !== 'application/vnd.in-toto+json' || !/^sha256:[a-f0-9]{64}$/.test(layer.digest) || blobHashes.get(name) !== layer.digest.slice(7))
+                if (layer.mediaType !== 'application/vnd.in-toto+json' ||
+                    !/^sha256:[a-f0-9]{64}$/.test(layer.digest) ||
+                    blobHashes.get(name) !== layer.digest.slice(7))
                     throw new Error('invalid attestation layer');
             }
         };
@@ -163,7 +200,8 @@ export async function validateImageArchive(file, expectedRef, maxExpandedBytes =
             if (visited.has(desc.digest))
                 return;
             visited.add(desc.digest);
-            if (desc.annotations?.['io.containerd.image.name'] || desc.annotations?.['org.opencontainers.image.ref.name'])
+            if (desc.annotations?.['io.containerd.image.name'] ||
+                desc.annotations?.['org.opencontainers.image.ref.name'])
                 throw new Error('nested OCI metadata contains unexpected image names');
             const document = readBlob(desc.digest);
             if (Array.isArray(document.manifests)) {
@@ -179,14 +217,17 @@ export async function validateImageArchive(file, expectedRef, maxExpandedBytes =
             if (!configDescriptor?.digest || !Array.isArray(document.layers))
                 throw new Error('invalid OCI image manifest');
             const imageConfig = readBlob(configDescriptor.digest);
-            const attestation = desc.annotations?.['vnd.docker.reference.type'] === 'attestation-manifest' && desc.platform?.os === 'unknown' && desc.platform?.architecture === 'unknown';
+            const attestation = desc.annotations?.['vnd.docker.reference.type'] === 'attestation-manifest' &&
+                desc.platform?.os === 'unknown' &&
+                desc.platform?.architecture === 'unknown';
             if (attestation && isAttestationDocument(document, imageConfig)) {
-                verifyAttestation(document, document.subject?.digest || desc.annotations?.['vnd.docker.reference.digest']);
+                verifyAttestation(document, document.subject?.digest ||
+                    desc.annotations?.['vnd.docker.reference.digest']);
                 return;
             }
             if (configDescriptor.digest !== expectedConfig)
                 throw new Error('OCI graph configuration does not match saved image');
-            const layerPaths = document.layers.map(layer => {
+            const layerPaths = document.layers.map((layer) => {
                 if (!/^sha256:[a-f0-9]{64}$/.test(layer.digest))
                     throw new Error('invalid OCI layer digest');
                 const name = `blobs/sha256/${layer.digest.slice(7)}`;
@@ -207,12 +248,17 @@ export async function validateImageArchive(file, expectedRef, maxExpandedBytes =
         for (const extra of index.manifests.slice(1)) {
             const annotationNames = Object.keys(extra.annotations || {});
             const unexpected = () => new Error('OCI index contains an unexpected extra manifest');
-            if (annotationNames.length !== 1 || annotationNames[0] !== 'io.containerd.manifest.subject' || !/^sha256:[a-f0-9]{64}$/.test(extra.digest))
+            if (annotationNames.length !== 1 ||
+                annotationNames[0] !== 'io.containerd.manifest.subject' ||
+                !/^sha256:[a-f0-9]{64}$/.test(extra.digest))
                 throw unexpected();
             const document = readBlob(extra.digest);
             const configDescriptor = document.config;
             const subject = document.subject?.digest;
-            if (!configDescriptor?.digest || !Array.isArray(document.layers) || subject !== extra.annotations['io.containerd.manifest.subject'] || !isAttestationDocument(document, readBlob(configDescriptor.digest)))
+            if (!configDescriptor?.digest ||
+                !Array.isArray(document.layers) ||
+                subject !== extra.annotations['io.containerd.manifest.subject'] ||
+                !isAttestationDocument(document, readBlob(configDescriptor.digest)))
                 throw unexpected();
             verifyAttestation(document, subject);
         }
@@ -222,17 +268,34 @@ export async function validateImageArchive(file, expectedRef, maxExpandedBytes =
         const colon = expectedRef.lastIndexOf(':');
         const repo = expectedRef.slice(0, colon);
         const tag = expectedRef.slice(colon + 1);
-        if (JSON.stringify(Object.keys(repositories)) !== JSON.stringify([repo]) || JSON.stringify(Object.keys(repositories[repo])) !== JSON.stringify([tag]))
+        if (JSON.stringify(Object.keys(repositories)) !== JSON.stringify([repo]) ||
+            JSON.stringify(Object.keys(repositories[repo])) !== JSON.stringify([tag]))
             throw new Error('archive repositories contain unexpected image tags');
     }
     const config = JSON.parse(configBytes.toString());
     if (config.os !== 'linux' || !['amd64', 'arm64'].includes(config.architecture))
         throw new Error('only linux/amd64 and linux/arm64 image archives are supported');
-    return { imageId: `sha256:${createHash('sha256').update(configBytes).digest('hex')}`, platform: `${config.os}/${config.architecture}`, ...await hashArchive(file) };
+    return {
+        imageId: `sha256:${createHash('sha256').update(configBytes).digest('hex')}`,
+        platform: `${config.os}/${config.architecture}`,
+        ...(await hashArchive(file)),
+    };
 }
 export function verifyDownload(expected) {
     const hash = createHash('sha256');
     let bytes = 0;
-    return new Transform({ transform(chunk, _encoding, callback) { bytes += chunk.length; if (bytes > expected.sizeBytes)
-            return callback(new Error('image download exceeds expected size')); hash.update(chunk); callback(null, chunk); }, flush(callback) { callback(bytes === expected.sizeBytes && hash.digest('hex') === expected.sha256 ? undefined : new Error('image download checksum or size mismatch')); } });
+    return new Transform({
+        transform(chunk, _encoding, callback) {
+            bytes += chunk.length;
+            if (bytes > expected.sizeBytes)
+                return callback(new Error('image download exceeds expected size'));
+            hash.update(chunk);
+            callback(null, chunk);
+        },
+        flush(callback) {
+            callback(bytes === expected.sizeBytes && hash.digest('hex') === expected.sha256
+                ? undefined
+                : new Error('image download checksum or size mismatch'));
+        },
+    });
 }

package/dist/build.d.ts

@@ -19,4 +19,4 @@ export interface BuildAndPushOptions {
     imageRef: string;
     push?: boolean;
 }
-export declare function buildAndPush({ contextDir, service, buildSpec, imageRef, push }: BuildAndPushOptions): Promise<void>;
+export declare function buildAndPush({ contextDir, service, buildSpec, imageRef, push, }: BuildAndPushOptions): Promise<void>;

package/dist/build.js

@@ -8,10 +8,12 @@ export function run(cmd, args, opts = {}) {
     return new Promise((resolve, reject) => {
         const p = spawn(cmd, args, { ...opts, stdio: ['ignore', 'pipe', 'pipe'] });
         let out = '', err = '';
-        p.stdout.on('data', d => out += d);
-        p.stderr.on('data', d => err += d);
+        p.stdout.on('data', (d) => (out += d));
+        p.stderr.on('data', (d) => (err += d));
         p.on('error', reject);
-        p.on('close', code => code === 0 ? resolve({ out, err }) : reject(new Error(`${cmd} ${args.join(' ')} failed (${code})\n${out}\n${err}`)));
+        p.on('close', (code) => code === 0
+            ? resolve({ out, err })
+            : reject(new Error(`${cmd} ${args.join(' ')} failed (${code})\n${out}\n${err}`)));
     });
 }
 export async function unpackContext(tarball, dest) {
@@ -19,22 +21,29 @@ export async function unpackContext(tarball, dest) {
     await ensureDir(dest);
     let expanded = 0;
     let entries = 0;
-    await scanArchive(tarball, entry => {
+    await scanArchive(tarball, (entry) => {
         expanded += entry.size;
         entries++;
-        if (expanded > 20 * 1024 ** 3 || entries > 100000 || path.isAbsolute(entry.path) || entry.path.split('/').includes('..') || !['File', 'Directory'].includes(entry.type))
+        if (expanded > 20 * 1024 ** 3 ||
+            entries > 100000 ||
+            path.isAbsolute(entry.path) ||
+            entry.path.split('/').includes('..') ||
+            !['File', 'Directory'].includes(entry.type))
             throw new Error('source context has unsafe entries or exceeds expanded limits');
     });
     await tar.x({ file: tarball, cwd: dest, strict: true });
 }
-export async function buildAndPush({ contextDir, service, buildSpec, imageRef, push = true }) {
+export async function buildAndPush({ contextDir, service, buildSpec, imageRef, push = true, }) {
     const buildPath = typeof buildSpec === 'string' ? buildSpec : buildSpec?.context || '.';
-    const dockerfilePath = typeof buildSpec === 'object' && buildSpec.dockerfile ? path.resolve(contextDir, buildPath, buildSpec.dockerfile) : undefined;
+    const dockerfilePath = typeof buildSpec === 'object' && buildSpec.dockerfile
+        ? path.resolve(contextDir, buildPath, buildSpec.dockerfile)
+        : undefined;
     if (dockerfilePath && !dockerfilePath.startsWith(`${path.resolve(contextDir)}${path.sep}`))
         throw new Error(`Dockerfile escapes uploaded root for ${service}`);
     const dockerfile = dockerfilePath ? ['-f', dockerfilePath] : [];
     const fullContext = path.resolve(contextDir, buildPath);
-    if (fullContext !== path.resolve(contextDir) && !fullContext.startsWith(`${path.resolve(contextDir)}${path.sep}`))
+    if (fullContext !== path.resolve(contextDir) &&
+        !fullContext.startsWith(`${path.resolve(contextDir)}${path.sep}`))
         throw new Error(`build context escapes uploaded root for ${service}`);
     if (!(await exists(fullContext)))
         throw new Error(`build context not found for ${service}: ${buildPath}`);

package/dist/cli-build.js

@@ -6,25 +6,45 @@ import { buildAndPush, run } from "./build.js";
 import { saveImageArchive } from "./artifacts.js";
 /** Credential exclusions are mandatory and cannot be re-included by source ignore rules. */
 export function sourceArchiveFilter(entry, configPaths, ignores) {
-    const relative = entry.replaceAll('\\', '/').replace(/^(\.\/)+/, '').replace(/\/$/, '');
-    if (relative.split('/').some(part => ['.git', '.tug.json'].includes(part)))
+    const relative = entry
+        .replaceAll('\\', '/')
+        .replace(/^(\.\/)+/, '')
+        .replace(/\/$/, '');
+    if (relative.split('/').some((part) => ['.git', '.tug.json'].includes(part)))
         return false;
-    return ![...configPaths, ...ignores].some(ignore => relative === ignore || relative.startsWith(`${ignore}/`));
+    return ![...configPaths, ...ignores].some((ignore) => relative === ignore || relative.startsWith(`${ignore}/`));
 }
 export async function createSourceArchive(contextDir, archive, configFiles) {
-    const configPaths = configFiles.map(file => path.relative(contextDir, file).split(path.sep).join('/')).filter(file => file !== '..' && !file.startsWith('../') && !path.isAbsolute(file));
+    const configPaths = configFiles
+        .map((file) => path.relative(contextDir, file).split(path.sep).join('/'))
+        .filter((file) => file !== '..' && !file.startsWith('../') && !path.isAbsolute(file));
     const ignores = ['node_modules', 'data', 'registry-data'];
     try {
-        ignores.push(...(await fs.readFile(path.join(contextDir, '.dockerignore'), 'utf8')).split(/\r?\n/).map(line => line.trim().replace(/\/$/, '')).filter(line => line && !line.startsWith('#') && !line.startsWith('!')));
+        ignores.push(...(await fs.readFile(path.join(contextDir, '.dockerignore'), 'utf8'))
+            .split(/\r?\n/)
+            .map((line) => line.trim().replace(/\/$/, ''))
+            .filter((line) => line && !line.startsWith('#') && !line.startsWith('!')));
     }
     catch (error) {
         if (error.code !== 'ENOENT')
             throw error;
     }
-    await tar.c({ gzip: true, file: archive, cwd: contextDir, filter: entry => sourceArchiveFilter(entry, configPaths, ignores) }, ['.']);
+    await tar.c({
+        gzip: true,
+        file: archive,
+        cwd: contextDir,
+        filter: (entry) => sourceArchiveFilter(entry, configPaths, ignores),
+    }, ['.']);
 }
 /** Build only application build services; callers own temporary files and upload transport. */
-export async function prepareLocalImages(compose, contextDir, directory, dependencies = { build: buildAndPush, save: saveImageArchive, nonce: randomUUID, remove: async (imageRef) => { await run('docker', ['image', 'rm', imageRef]); } }) {
+export async function prepareLocalImages(compose, contextDir, directory, dependencies = {
+    build: buildAndPush,
+    save: saveImageArchive,
+    nonce: randomUUID,
+    remove: async (imageRef) => {
+        await run('docker', ['image', 'rm', imageRef]);
+    },
+}) {
     const images = [];
     const nonce = dependencies.nonce();
     for (const [service, spec] of Object.entries(compose.services)) {
@@ -33,7 +53,13 @@ export async function prepareLocalImages(compose, contextDir, directory, depende
         const field = `image-${images.length}`;
         const imageRef = `tug-build/${nonce}/${field}:local`;
         try {
-            await dependencies.build({ contextDir, service, buildSpec: spec.build, imageRef, push: false });
+            await dependencies.build({
+                contextDir,
+                service,
+                buildSpec: spec.build,
+                imageRef,
+                push: false,
+            });
             const archive = await dependencies.save(imageRef, path.join(directory, `${field}.tar.gz`));
             images.push({ service, imageRef, ...archive, field });
         }

package/dist/cli-config.js

@@ -4,7 +4,7 @@ import path from 'node:path';
 export async function resolveCliConfig(options, env, cwd, creating = false) {
     for (const key of ['config', 'controlUrl', 'project'])
         if (options[key] !== undefined && (!options[key].trim() || /[\r\n\0]/.test(options[key])))
-            throw new Error(`--${key.replace(/[A-Z]/g, c => '-' + c.toLowerCase())} must be a nonempty single-line value`);
+            throw new Error(`--${key.replace(/[A-Z]/g, (c) => '-' + c.toLowerCase())} must be a nonempty single-line value`);
     const file = path.resolve(cwd, options.config || env.TUG_CONFIG || '.tug.json');
     let config = {};
     try {
@@ -24,7 +24,12 @@ export async function resolveCliConfig(options, env, cwd, creating = false) {
             throw new Error(`Cannot read config ${file}: ${error.message}`, { cause: error });
     }
     const controlUrl = options.controlUrl || env.TUG_CONTROL_URL || config.controlUrl || 'http://localhost:8080';
-    return { file, controlUrl: normalizeControlUrl(controlUrl), operatorToken: env.TUG_TOKEN || config.operatorToken, project: options.project || env.TUG_PROJECT || config.project || 'site' };
+    return {
+        file,
+        controlUrl: normalizeControlUrl(controlUrl),
+        operatorToken: env.TUG_TOKEN || config.operatorToken,
+        project: options.project || env.TUG_PROJECT || config.project || 'site',
+    };
 }
 export function normalizeControlUrl(value) {
     if (!value.trim() || /[\r\n\0]/.test(value))
@@ -36,12 +41,19 @@ export function normalizeControlUrl(value) {
     catch {
         throw new Error('control URL must be an absolute http:// or https:// URL');
     }
-    if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash)
+    if (!['http:', 'https:'].includes(url.protocol) ||
+        url.username ||
+        url.password ||
+        url.search ||
+        url.hash)
         throw new Error('control URL must use http:// or https:// without credentials, query or fragment');
     return value.replace(/\/+$/, '');
 }
 export function integerOption(value, name, minimum = 1, maximum = Number.MAX_SAFE_INTEGER) {
-    if (!/^\d+$/.test(value) || !Number.isSafeInteger(Number(value)) || Number(value) < minimum || Number(value) > maximum)
+    if (!/^\d+$/.test(value) ||
+        !Number.isSafeInteger(Number(value)) ||
+        Number(value) < minimum ||
+        Number(value) > maximum)
         throw new Error(`${name} must be an integer from ${minimum} to ${maximum}`);
     return Number(value);
 }

package/dist/cli-install.d.ts

@@ -1,7 +1,17 @@
+/** The agent dials container IPs for health checks; from the default bridge they are unreachable on current Docker (29.x), so it always shares the host network namespace. */
+export declare const HOST_NETWORK_FLAG = "--network host";
 export declare const MESH_RUN_FLAGS = "--network host --cap-add NET_ADMIN";
+/** Docker platform for the architecture a host reports with `uname -m`. */
+export declare function dockerPlatform(uname: string): string;
+/** Build for the host the image will run on, not the machine that builds it (an arm64 laptop and an amd64 VPS differ). */
+export declare function localImageBuildArgs(imageTag: string, uname: string): string[];
 export declare function shellQuote(value: unknown): string;
 export declare function dockerRunSnippet(image: string, joinKey: string, mesh?: boolean): string;
 /** The bootstrap runs in its own shell so its idempotent early exit cannot skip enrollment. */
 export declare function enrollmentCloudInit(bootstrap: string, command: string): string;
+/** Name of the container `control-install` creates (Compose project `tug-control`, service `control`). */
+export declare const CONTROL_CONTAINER = "tug-control-control-1";
+/** A TCP port is free, or is held by the control container this install would replace, so installing again upgrades in place. */
+export declare function controlPortCheck(port: number): string;
 /** An occupied mesh port is reusable only when the installed Tug agent owns the live key. */
 export declare function meshPortCheck(port: number): string;

package/dist/cli-install.js

@@ -1,12 +1,46 @@
 import yaml from 'js-yaml';
-export const MESH_RUN_FLAGS = '--network host --cap-add NET_ADMIN';
-export function shellQuote(value) { return `'${String(value).replace(/'/g, `'\\''`)}'`; }
+/** The agent dials container IPs for health checks; from the default bridge they are unreachable on current Docker (29.x), so it always shares the host network namespace. */
+export const HOST_NETWORK_FLAG = '--network host';
+export const MESH_RUN_FLAGS = `${HOST_NETWORK_FLAG} --cap-add NET_ADMIN`;
+/** Docker platform for the architecture a host reports with `uname -m`. */
+export function dockerPlatform(uname) {
+    const arch = uname.trim();
+    if (arch === 'x86_64' || arch === 'amd64')
+        return 'linux/amd64';
+    if (arch === 'aarch64' || arch === 'arm64')
+        return 'linux/arm64';
+    throw new Error(`unsupported host architecture '${arch}'; --build-local-image supports x86_64 and aarch64`);
+}
+/** Build for the host the image will run on, not the machine that builds it (an arm64 laptop and an amd64 VPS differ). */
+export function localImageBuildArgs(imageTag, uname) {
+    return ['build', '--platform', dockerPlatform(uname), '-t', imageTag, '.'];
+}
+export function shellQuote(value) {
+    return `'${String(value).replace(/'/g, `'\\''`)}'`;
+}
 export function dockerRunSnippet(image, joinKey, mesh = false) {
-    return `docker run -d --name tug-agent --restart unless-stopped ${mesh ? `${MESH_RUN_FLAGS} -e TUG_MESH=true ` : ''}-v /var/run/docker.sock:/var/run/docker.sock -v tug-agent:/var/lib/tug -e TUG_JOIN_KEY=${shellQuote(joinKey)} ${shellQuote(image)} agent`;
+    return `docker run -d --name tug-agent --restart unless-stopped ${mesh ? `${MESH_RUN_FLAGS} -e TUG_MESH=true ` : `${HOST_NETWORK_FLAG} `}-v /var/run/docker.sock:/var/run/docker.sock -v tug-agent:/var/lib/tug -e TUG_JOIN_KEY=${shellQuote(joinKey)} ${shellQuote(image)} agent`;
 }
 /** The bootstrap runs in its own shell so its idempotent early exit cannot skip enrollment. */
 export function enrollmentCloudInit(bootstrap, command) {
-    return '#cloud-config\n' + yaml.dump({ write_files: [{ path: '/opt/tug/install-docker.sh', permissions: '0700', content: bootstrap }], runcmd: [['sh', '-eu', '-c', `sh /opt/tug/install-docker.sh && ${command}`]] }, { lineWidth: -1, noRefs: true });
+    return ('#cloud-config\n' +
+        yaml.dump({
+            write_files: [
+                { path: '/opt/tug/install-docker.sh', permissions: '0700', content: bootstrap },
+            ],
+            runcmd: [['sh', '-eu', '-c', `sh /opt/tug/install-docker.sh && ${command}`]],
+        }, { lineWidth: -1, noRefs: true }));
+}
+/** Name of the container `control-install` creates (Compose project `tug-control`, service `control`). */
+export const CONTROL_CONTAINER = 'tug-control-control-1';
+/** A TCP port is free, or is held by the control container this install would replace, so installing again upgrades in place. */
+export function controlPortCheck(port) {
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+        throw new Error('port must be an integer from 1 to 65535');
+    return `command -v ss >/dev/null 2>&1 || exit 0
+ss -ltn | awk '{print $4}' | grep -qE '[.:]${port}$' || exit 0
+[ -n "$(docker ps -q --filter 'name=^/${CONTROL_CONTAINER}$' --filter 'publish=${port}' 2>/dev/null)" ]
+`;
 }
 /** An occupied mesh port is reusable only when the installed Tug agent owns the live key. */
 export function meshPortCheck(port) {

package/dist/cli-live-transport.d.ts

@@ -0,0 +1,3 @@
+import type { CliLiveTransport } from './cli-live.ts';
+/** Credentials travel only in the upgrade header, never a URL or frame. */
+export declare function createCliLiveTransport(controlUrl: string, operatorToken?: string): CliLiveTransport;