@ebowwa/seedinstallation 0.2.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ebowwa Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,172 @@
+# @cheapspaces/seedInstallation
+
+Composable server installation utilities for edge deployment automation. This package provides a set of utilities for provisioning and managing servers, both locally and via SSH.
+
+## Features
+
+- **Sudo command execution** - Run commands with sudo privileges locally or via SSH
+- **Package management** - Install system packages (apt, dnf, apk)
+- **File operations** - Write to privileged paths with proper permissions
+- **Systemd service management** - Create, enable, and manage systemd services
+- **Runtime installation** - Install and configure runtimes like Bun
+- **Device-code authentication** - Handle OAuth device flows for Doppler, GitHub, Tailscale
+- **Bootstrap tracking** - Track provisioning phases and status
+- **Git cloning** - Composable git clone with shallow/sparse support
+
+## Installation
+
+```bash
+npm install @cheapspaces/seedInstallation
+```
+
+## Usage
+
+### Local Command Execution
+
+```typescript
+import { sudo, pkgInstall } from '@cheapspaces/seedInstallation';
+
+// Run a command with sudo
+const result = await sudo(['apt-get', 'update'], {
+  context: { type: 'local' }
+});
+
+// Install packages
+await pkgInstall(['git', 'curl', 'vim'], {
+  context: { type: 'local' },
+  pm: 'apt'
+});
+```
+
+### Remote SSH Execution
+
+```typescript
+import { sudo, writeFile } from '@cheapspaces/seedInstallation';
+
+// Run commands over SSH
+const result = await sudo(['systemctl', 'status', 'nginx'], {
+  context: {
+    type: 'ssh',
+    host: '192.168.1.100',
+    user: 'root',
+    keyPath: '/path/to/key'
+  }
+});
+
+// Write files to remote server
+await writeFile('/etc/nginx/nginx.conf', configContent, {
+  context: { type: 'ssh', host: '192.168.1.100' },
+  mode: '644'
+});
+```
+
+### Systemd Service Management
+
+```typescript
+import {
+  createServiceUnit,
+  enableAndStartService,
+  getServiceStatus
+} from '@cheapspaces/seedInstallation';
+
+// Create a systemd service
+await createServiceUnit('myapp', {
+  description: 'My Application',
+  workingDirectory: '/opt/myapp',
+  execStart: '/usr/bin/node /opt/myapp/index.js',
+  restart: 'always',
+  environment: {
+    NODE_ENV: 'production'
+  }
+}, { context: { type: 'local' } });
+
+// Enable and start the service
+await enableAndStartService('myapp', {
+  context: { type: 'local' }
+});
+
+// Check service status
+const status = await getServiceStatus('myapp', {
+  context: { type: 'local' }
+});
+```
+
+### Device-Code Authentication
+
+```typescript
+import { deviceAuth, dopplerConfig } from '@cheapspaces/seedInstallation';
+
+// Authenticate with Doppler via device code
+const result = await deviceAuth(dopplerConfig, {
+  context: { type: 'local' },
+  onPoll: (attempt, result) => {
+    console.log(`Polling... attempt ${attempt}`);
+  }
+});
+
+if (result.success) {
+  console.log(`Visit: ${result.url}`);
+  console.log(`Code: ${result.code}`);
+}
+```
+
+### Git Cloning
+
+```typescript
+import { clone } from '@cheapspaces/seedInstallation/clone';
+
+// Basic clone
+const { path, commit } = await clone({
+  repo: 'https://github.com/user/repo.git'
+});
+
+// Shallow clone of specific branch
+await clone({
+  repo: 'https://github.com/user/repo.git',
+  ref: 'main',
+  depth: 1,
+  dest: 'my-repo'
+});
+
+// Sparse checkout (only specific paths)
+await clone({
+  repo: 'https://github.com/user/repo.git',
+  sparse: ['src/lib', 'src/types'],
+  depth: 1
+});
+```
+
+## API
+
+### Modules
+
+- `.` - Main exports (all utilities)
+- `./clone` - Git clone utilities
+- `./sudo` - Sudo command execution
+- `./runtime` - Runtime installation and PATH management
+- `./systemd` - Systemd service management
+- `./device-auth` - Device-code authentication flows
+- `./bootstrap` - Bootstrap status tracking
+
+### Types
+
+```typescript
+interface ExecContext {
+  type: 'local' | 'ssh';
+  host?: string;
+  user?: string;
+  keyPath?: string;
+  port?: number;
+}
+
+interface ExecResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+  ok: boolean;
+}
+```
+
+## License
+
+MIT

package/dist/bootstrap.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Bootstrap/provisioning status tracking for edge servers.
+ * Manages phase markers, status files, and polling for completion.
+ * Works with both local and SSH contexts via ExecContext from sudo.ts.
+ */
+import type { SudoOptions, ExecResult } from "./sudo.js";
+export interface BootstrapPhase {
+    /** Phase name (e.g. "bun", "seed", "doppler") */
+    name: string;
+    /** Current status of this phase */
+    status: "pending" | "running" | "complete" | "failed";
+    /** ISO timestamp when phase started */
+    startedAt?: string;
+    /** ISO timestamp when phase completed */
+    completedAt?: string;
+    /** Error message if failed */
+    error?: string;
+}
+export interface BootstrapStatus {
+    /** Overall bootstrap status */
+    status: "started" | "running" | "complete" | "failed";
+    /** ISO timestamp when bootstrap started */
+    startedAt?: string;
+    /** ISO timestamp when bootstrap completed */
+    completedAt?: string;
+    /** Source of bootstrap (e.g. "cloud-init", "manual") */
+    source?: string;
+    /** Individual phase statuses */
+    phases: Record<string, BootstrapPhase>;
+    /** Raw file content */
+    raw: string;
+}
+export interface BootstrapPollOptions {
+    /** Execution context for running commands */
+    context: SudoOptions["context"];
+    /** Maximum poll attempts (default: 30) */
+    maxAttempts?: number;
+    /** Interval between polls in ms (default: 2000) */
+    intervalMs?: number;
+    /** Callback called on each poll attempt */
+    onProgress?: (attempt: number, status: BootstrapStatus) => void;
+}
+/**
+ * Read and parse a bootstrap status file.
+ *
+ * File format is key=value lines:
+ * ```
+ * status=started
+ * started_at=2024-01-01T00:00:00+00:00
+ * source=cloud-init
+ * phase.bun.status=complete
+ * phase.bun.completed_at=2024-01-01T00:01:00+00:00
+ * phase.seed.status=running
+ * phase.seed.started_at=2024-01-01T00:01:30+00:00
+ * ```
+ */
+export declare function getBootstrapStatus(statusFile: string, opts: SudoOptions): Promise<BootstrapStatus>;
+/**
+ * Parse bootstrap status from file content.
+ */
+export declare function parseBootstrapStatus(content: string): BootstrapStatus;
+/**
+ * Write initial bootstrap status file.
+ */
+export declare function initBootstrap(statusFile: string, source: string, opts: SudoOptions): Promise<ExecResult>;
+/**
+ * Mark a phase as started.
+ */
+export declare function startPhase(statusFile: string, phase: string, opts: SudoOptions): Promise<ExecResult>;
+/**
+ * Mark a phase as complete.
+ */
+export declare function completePhase(statusFile: string, phase: string, opts: SudoOptions): Promise<ExecResult>;
+/**
+ * Mark a phase as failed.
+ */
+export declare function failPhase(statusFile: string, phase: string, error: string, opts: SudoOptions): Promise<ExecResult>;
+/**
+ * Mark entire bootstrap as complete.
+ */
+export declare function completeBootstrap(statusFile: string, opts: SudoOptions): Promise<ExecResult>;
+/**
+ * Mark bootstrap as failed.
+ */
+export declare function failBootstrap(statusFile: string, error: string, opts: SudoOptions): Promise<ExecResult>;
+/**
+ * Check if a marker file exists.
+ * Use for simple completion flags (e.g. .seed-setup-complete).
+ */
+export declare function checkMarker(markerPath: string, opts: SudoOptions): Promise<boolean>;
+/**
+ * Create a marker file.
+ */
+export declare function setMarker(markerPath: string, opts: SudoOptions): Promise<ExecResult>;
+/**
+ * Remove a marker file.
+ */
+export declare function removeMarker(markerPath: string, opts: SudoOptions): Promise<ExecResult>;
+/**
+ * Poll until bootstrap completes or times out.
+ *
+ * Returns the final status (complete or failed/timeout).
+ */
+export declare function waitForBootstrap(statusFile: string, opts: BootstrapPollOptions): Promise<{
+    completed: boolean;
+    status: BootstrapStatus;
+}>;
+/**
+ * Poll until a marker file exists.
+ */
+export declare function waitForMarker(markerPath: string, opts: BootstrapPollOptions): Promise<{
+    exists: boolean;
+    timedOut: boolean;
+}>;

package/dist/bootstrap.js

@@ -0,0 +1,225 @@
+/**
+ * Bootstrap/provisioning status tracking for edge servers.
+ * Manages phase markers, status files, and polling for completion.
+ * Works with both local and SSH contexts via ExecContext from sudo.ts.
+ */
+// Re-export helpers
+async function exec(args, opts) {
+    const { sudo } = await import("./sudo.js");
+    return sudo(args, opts);
+}
+async function writeFile(path, content, opts) {
+    const { writeFile: wf } = await import("./sudo.js");
+    return wf(path, content, opts);
+}
+// ---------------------------------------------------------------------------
+// Status file parsing
+// ---------------------------------------------------------------------------
+/**
+ * Read and parse a bootstrap status file.
+ *
+ * File format is key=value lines:
+ * ```
+ * status=started
+ * started_at=2024-01-01T00:00:00+00:00
+ * source=cloud-init
+ * phase.bun.status=complete
+ * phase.bun.completed_at=2024-01-01T00:01:00+00:00
+ * phase.seed.status=running
+ * phase.seed.started_at=2024-01-01T00:01:30+00:00
+ * ```
+ */
+export async function getBootstrapStatus(statusFile, opts) {
+    const result = await exec(["cat", statusFile], { ...opts, quiet: true });
+    if (!result.ok) {
+        // File doesn't exist or isn't readable
+        return {
+            status: "started",
+            phases: {},
+            raw: "",
+        };
+    }
+    return parseBootstrapStatus(result.stdout);
+}
+/**
+ * Parse bootstrap status from file content.
+ */
+export function parseBootstrapStatus(content) {
+    const phases = {};
+    const data = {};
+    // Parse key=value lines
+    for (const line of content.trim().split("\n")) {
+        if (!line || !line.includes("="))
+            continue;
+        const [key, ...valueParts] = line.split("=");
+        const value = valueParts.join("=").trim();
+        data[key] = value;
+    }
+    // Extract overall status
+    const status = (data.status || "started");
+    const startedAt = data.started_at;
+    const completedAt = data.completed_at;
+    const source = data.source;
+    // Extract phases
+    for (const [key, value] of Object.entries(data)) {
+        if (!key.startsWith("phase."))
+            continue;
+        // phase.{name}.{field}
+        const parts = key.split(".");
+        if (parts.length < 3)
+            continue;
+        const [, phaseName, field] = parts;
+        if (!phases[phaseName]) {
+            phases[phaseName] = { name: phaseName, status: "pending" };
+        }
+        switch (field) {
+            case "status":
+                phases[phaseName].status = value;
+                break;
+            case "started_at":
+                phases[phaseName].startedAt = value;
+                break;
+            case "completed_at":
+                phases[phaseName].completedAt = value;
+                break;
+            case "error":
+                phases[phaseName].error = value;
+                break;
+        }
+    }
+    return {
+        status,
+        startedAt,
+        completedAt,
+        source,
+        phases,
+        raw: content,
+    };
+}
+// ---------------------------------------------------------------------------
+// Status file writing
+// ---------------------------------------------------------------------------
+/**
+ * Write initial bootstrap status file.
+ */
+export async function initBootstrap(statusFile, source, opts) {
+    const now = new Date().toISOString();
+    const content = `status=started\nstarted_at=${now}\nsource=${source}\n`;
+    return writeFile(statusFile, content, opts);
+}
+/**
+ * Mark a phase as started.
+ */
+export async function startPhase(statusFile, phase, opts) {
+    const now = new Date().toISOString();
+    const line = `phase.${phase}.status=running\nphase.${phase}.started_at=${now}\n`;
+    return writeFile(statusFile, line, { ...opts, append: true });
+}
+/**
+ * Mark a phase as complete.
+ */
+export async function completePhase(statusFile, phase, opts) {
+    const now = new Date().toISOString();
+    const line = `phase.${phase}.status=complete\nphase.${phase}.completed_at=${now}\n`;
+    return writeFile(statusFile, line, { ...opts, append: true });
+}
+/**
+ * Mark a phase as failed.
+ */
+export async function failPhase(statusFile, phase, error, opts) {
+    const now = new Date().toISOString();
+    const safeError = error.replace(/\n/g, " "); // Don't break the format
+    const line = `phase.${phase}.status=failed\nphase.${phase}.completed_at=${now}\nphase.${phase}.error=${safeError}\n`;
+    return writeFile(statusFile, line, { ...opts, append: true });
+}
+/**
+ * Mark entire bootstrap as complete.
+ */
+export async function completeBootstrap(statusFile, opts) {
+    const now = new Date().toISOString();
+    const line = `status=complete\ncompleted_at=${now}\n`;
+    return writeFile(statusFile, line, { ...opts, append: true });
+}
+/**
+ * Mark bootstrap as failed.
+ */
+export async function failBootstrap(statusFile, error, opts) {
+    const now = new Date().toISOString();
+    const safeError = error.replace(/\n/g, " ");
+    const line = `status=failed\ncompleted_at=${now}\nerror=${safeError}\n`;
+    return writeFile(statusFile, line, { ...opts, append: true });
+}
+// ---------------------------------------------------------------------------
+// Marker files
+// ---------------------------------------------------------------------------
+/**
+ * Check if a marker file exists.
+ * Use for simple completion flags (e.g. .seed-setup-complete).
+ */
+export async function checkMarker(markerPath, opts) {
+    const result = await exec(["test", "-f", markerPath, "&&", "echo", "exists"], {
+        ...opts,
+        quiet: true,
+    });
+    return result.ok && result.stdout.trim() === "exists";
+}
+/**
+ * Create a marker file.
+ */
+export async function setMarker(markerPath, opts) {
+    return exec(["touch", markerPath], opts);
+}
+/**
+ * Remove a marker file.
+ */
+export async function removeMarker(markerPath, opts) {
+    return exec(["rm", "-f", markerPath], opts);
+}
+// ---------------------------------------------------------------------------
+// Polling
+// ---------------------------------------------------------------------------
+/**
+ * Poll until bootstrap completes or times out.
+ *
+ * Returns the final status (complete or failed/timeout).
+ */
+export async function waitForBootstrap(statusFile, opts) {
+    const maxAttempts = opts.maxAttempts ?? 30;
+    const intervalMs = opts.intervalMs ?? 2000;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        const status = await getBootstrapStatus(statusFile, opts);
+        if (status.status === "complete") {
+            return { completed: true, status };
+        }
+        if (status.status === "failed") {
+            return { completed: false, status };
+        }
+        opts.onProgress?.(attempt, status);
+        await sleep(intervalMs);
+    }
+    // Timeout - get final status for error info
+    const finalStatus = await getBootstrapStatus(statusFile, opts);
+    return { completed: false, status: finalStatus };
+}
+/**
+ * Poll until a marker file exists.
+ */
+export async function waitForMarker(markerPath, opts) {
+    const maxAttempts = opts.maxAttempts ?? 30;
+    const intervalMs = opts.intervalMs ?? 2000;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        const exists = await checkMarker(markerPath, opts);
+        if (exists) {
+            return { exists: true, timedOut: false };
+        }
+        opts.onProgress?.(attempt, { status: "running" });
+        await sleep(intervalMs);
+    }
+    return { exists: false, timedOut: true };
+}
+// ---------------------------------------------------------------------------
+// Utilities
+// ---------------------------------------------------------------------------
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/clone.d.ts

@@ -0,0 +1,36 @@
+export interface CloneOptions {
+    /** Repository URL (HTTPS or SSH) */
+    repo: string;
+    /** Target directory (defaults to repo name) */
+    dest?: string;
+    /** Clone specific branch, tag, or ref */
+    ref?: string;
+    /** Shallow clone depth (e.g. 1 for latest commit only) */
+    depth?: number;
+    /** Sparse checkout: only clone these paths */
+    sparse?: string[];
+    /** Working directory to clone into (defaults to cwd) */
+    cwd?: string;
+}
+export interface CloneResult {
+    /** Absolute path to the cloned repo */
+    path: string;
+    /** The ref that was checked out */
+    ref: string;
+    /** Short commit hash */
+    commit: string;
+}
+/**
+ * Composable git clone with support for shallow, sparse, branch, and directory options.
+ *
+ * @example
+ * // Basic clone
+ * await clone({ repo: "https://github.com/org/repo.git" });
+ *
+ * // Shallow clone of a specific branch into a custom dir
+ * await clone({ repo: "https://github.com/org/repo.git", ref: "main", depth: 1, dest: "my-repo" });
+ *
+ * // Sparse checkout — only pull specific subdirectories
+ * await clone({ repo: "https://github.com/org/repo.git", sparse: ["src/lib", "src/types"], depth: 1 });
+ */
+export declare function clone(opts: CloneOptions): Promise<CloneResult>;

package/dist/clone.js

@@ -0,0 +1,74 @@
+import { spawn } from "child_process";
+/**
+ * Composable git clone with support for shallow, sparse, branch, and directory options.
+ *
+ * @example
+ * // Basic clone
+ * await clone({ repo: "https://github.com/org/repo.git" });
+ *
+ * // Shallow clone of a specific branch into a custom dir
+ * await clone({ repo: "https://github.com/org/repo.git", ref: "main", depth: 1, dest: "my-repo" });
+ *
+ * // Sparse checkout — only pull specific subdirectories
+ * await clone({ repo: "https://github.com/org/repo.git", sparse: ["src/lib", "src/types"], depth: 1 });
+ */
+export async function clone(opts) {
+    const { repo, dest, ref, depth, sparse, cwd } = opts;
+    const repoName = dest ?? repoNameFrom(repo);
+    const targetDir = cwd ? `${cwd}/${repoName}` : repoName;
+    const args = ["git", "clone"];
+    if (depth)
+        args.push("--depth", String(depth));
+    if (ref && !sparse)
+        args.push("--branch", ref);
+    if (sparse)
+        args.push("--no-checkout", "--filter=blob:none");
+    args.push(repo, targetDir);
+    await run(args, cwd);
+    if (sparse) {
+        await run(["git", "sparse-checkout", "init", "--cone"], targetDir);
+        await run(["git", "sparse-checkout", "set", ...sparse], targetDir);
+        if (ref) {
+            await run(["git", "checkout", ref], targetDir);
+        }
+        else {
+            await run(["git", "checkout"], targetDir);
+        }
+    }
+    const commit = (await run(["git", "rev-parse", "--short", "HEAD"], targetDir)).trim();
+    const checkedRef = (await run(["git", "rev-parse", "--abbrev-ref", "HEAD"], targetDir)).trim();
+    const absPath = (await run(["git", "rev-parse", "--show-toplevel"], targetDir)).trim();
+    return { path: absPath, ref: checkedRef, commit };
+}
+/** Extract repo name from a git URL */
+function repoNameFrom(url) {
+    return url.replace(/\.git$/, "").split("/").pop();
+}
+/** Run a command and return stdout, throw on failure */
+async function run(args, cwd) {
+    return new Promise((resolve, reject) => {
+        const proc = spawn(args[0], args.slice(1), {
+            cwd: cwd || undefined,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        proc.stdout?.on("data", (data) => {
+            stdout += data.toString();
+        });
+        proc.stderr?.on("data", (data) => {
+            stderr += data.toString();
+        });
+        proc.on("close", (code) => {
+            if (code === 0) {
+                resolve(stdout);
+            }
+            else {
+                reject(new Error(`${args.join(" ")} failed (exit ${code}): ${stderr}`));
+            }
+        });
+        proc.on("error", (err) => {
+            reject(new Error(`${args.join(" ")} failed: ${err.message}`));
+        });
+    });
+}