@itznexus/itznexus-cli 1.141.0 → 1.143.0

package/dist/lib/stack/driver.js

@@ -0,0 +1,228 @@
+import path from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+import { readStackManifest, } from "./manifest.js";
+import { alive, composeProjects, gitBranch, hashFile, killGroup, logTail, probeOnce, runStep, spawnDetached, waitReady, } from "./processes.js";
+import { listRecords, logPath, readRecord, removeRecord, writeRecord, } from "./registry.js";
+const now = () => new Date().toISOString();
+// Branch of the first service folder that is a git clone; every clone of a
+// project sits on the same branch during a batch, so one is enough.
+function stackBranch(manifest) {
+    for (const s of manifest.services) {
+        const branch = gitBranch(s.cwd);
+        if (branch)
+            return branch;
+    }
+    return null;
+}
+// Installs run first, once per folder and lockfile, only when the lockfile
+// moved since the last install; a folder installed this way gets its start
+// services restarted below, since the running process holds the old modules.
+function runInstalls(manifest, rec) {
+    const refreshed = new Set();
+    const seen = new Set();
+    for (const s of manifest.services) {
+        if (!s.install || !s.lockfile)
+            continue;
+        const key = `${s.cwd}::${s.lockfile}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        const hash = hashFile(s.lockfile);
+        if (rec.installs[key] === hash)
+            continue;
+        console.log(`[stack] ${s.name}: lockfile moved, installing in ${path.basename(s.cwd)}`);
+        runStep(s.install, s.cwd, manifest.env);
+        rec.installs[key] = hash;
+        refreshed.add(s.cwd);
+        writeRecord(rec);
+    }
+    return refreshed;
+}
+function tryReadManifest(root) {
+    try {
+        return readStackManifest(root);
+    }
+    catch {
+        return null;
+    }
+}
+// A live process that misses one probe is not dead (a dev server recompiling,
+// a listener mid-restart): three misses in a row are.
+async function stillAnswers(probe) {
+    for (let i = 0; i < 3; i++) {
+        if (await probeOnce(probe))
+            return true;
+        await sleep(500);
+    }
+    return false;
+}
+async function startService(s, rec, env, restart) {
+    if (!s.ready)
+        throw new Error(`${s.name}: a start service needs a ready probe`);
+    const cur = rec.services[s.name];
+    const running = cur?.pid !== null && cur?.pid !== undefined && alive(cur.pid);
+    if (running && !restart && (await stillAnswers(s.ready)))
+        return;
+    if (running && cur.pid !== null)
+        await killGroup(cur.pid);
+    // A probe that already answers with no live pid of ours is a copy running
+    // outside the driver (an operator's terminal): never start a second one.
+    if (await probeOnce(s.ready)) {
+        throw new Error(`${s.name}: already answering on its port from a process the driver did not start; use it or stop it`);
+    }
+    const log = logPath(rec.slug, s.name);
+    const pid = spawnDetached(s.command, s.cwd, log, env);
+    rec.services[s.name] = { pid, startedAt: now() };
+    // Recorded before the wait, so a crash of the driver mid-up still leaves
+    // the pid known to a later down.
+    writeRecord(rec);
+    try {
+        await waitReady(s.ready, s.readyTimeoutMs, s.name, log, pid);
+    }
+    catch (err) {
+        await killGroup(pid);
+        rec.services[s.name] = { pid: null, startedAt: now() };
+        writeRecord(rec);
+        throw err;
+    }
+    console.log(`[stack] ${s.name}: up (pid ${pid})`);
+}
+export async function upStack(root) {
+    const manifest = readStackManifest(root);
+    // One stack per machine: another project's stack goes down first.
+    for (const other of listRecords()) {
+        if (other.slug !== manifest.slug)
+            await downRecord(other, true);
+    }
+    const branch = stackBranch(manifest);
+    let rec = readRecord(manifest.slug);
+    if (rec && rec.branch !== branch) {
+        console.log(`[stack] branch moved from ${rec.branch} to ${branch}: wiping the data`);
+        await downRecord(rec, true);
+        rec = null;
+    }
+    rec ??= {
+        slug: manifest.slug,
+        root,
+        branch,
+        startedAt: now(),
+        lastUsedAt: now(),
+        services: {},
+        ups: {},
+        installs: {},
+        composeProjects: [],
+    };
+    writeRecord(rec);
+    const refreshed = runInstalls(manifest, rec);
+    for (const s of manifest.services) {
+        if (s.kind === "up") {
+            const before = composeProjects();
+            runStep(s.command, s.cwd, manifest.env);
+            const after = composeProjects();
+            const added = before && after ? [...after].filter((p) => !before.has(p)) : [];
+            for (const p of added) {
+                if (!rec.composeProjects.includes(p))
+                    rec.composeProjects.push(p);
+            }
+            // Owned when this up made resources appear, or when Docker could not
+            // say; a resource that was already there belongs to whoever started it
+            // and is left as found on down.
+            if (!(s.name in rec.ups)) {
+                rec.ups[s.name] = { owned: added.length > 0 || before === null };
+            }
+            writeRecord(rec);
+            if (s.ready)
+                await waitReady(s.ready, s.readyTimeoutMs, s.name);
+        }
+        else if (s.kind === "run") {
+            runStep(s.command, s.cwd, manifest.env);
+        }
+        else {
+            await startService(s, rec, manifest.env, refreshed.has(s.cwd));
+        }
+    }
+    rec.lastUsedAt = now();
+    writeRecord(rec);
+    return stackStatus(root);
+}
+// Takes a recorded stack down from its own manifest when it still reads;
+// without one (folder gone, block removed) only the recorded pids are ended.
+async function downRecord(rec, wipe) {
+    const manifest = tryReadManifest(rec.root);
+    const ordered = manifest ? [...manifest.services].reverse() : [];
+    const env = manifest?.env ?? {};
+    for (const s of ordered) {
+        if (s.kind === "start") {
+            const pid = rec.services[s.name]?.pid;
+            if (pid && alive(pid))
+                await killGroup(pid);
+            rec.services[s.name] = { pid: null, startedAt: now() };
+        }
+        else if (s.kind === "up") {
+            const command = wipe ? (s.wipe ?? s.down) : s.down;
+            if (!command || !rec.ups[s.name]?.owned)
+                continue;
+            try {
+                runStep(command, s.cwd, env);
+            }
+            catch (err) {
+                console.error(`[stack] ${s.name}: ${command} failed:`, err);
+            }
+        }
+    }
+    // Services the manifest no longer names still hold a pid here.
+    for (const r of Object.values(rec.services)) {
+        if (r.pid && alive(r.pid))
+            await killGroup(r.pid);
+    }
+    removeRecord(rec.slug);
+    console.log(`[stack] ${rec.slug}: down${wipe ? " (data wiped)" : ""}`);
+}
+export async function downStack(root, wipe) {
+    const rec = readRecord(path.basename(root));
+    if (!rec)
+        return false;
+    await downRecord(rec, wipe);
+    return true;
+}
+export async function stackStatus(root) {
+    const manifest = readStackManifest(root);
+    const rec = readRecord(manifest.slug);
+    const rows = [];
+    for (const s of manifest.services) {
+        const pid = rec?.services[s.name]?.pid ?? null;
+        rows.push({
+            name: s.name,
+            kind: s.kind,
+            pid,
+            alive: pid !== null && alive(pid),
+            ready: s.ready ? await probeOnce(s.ready) : null,
+            log: s.kind === "start" ? logPath(manifest.slug, s.name) : null,
+        });
+    }
+    return rows;
+}
+export async function restartService(root, name) {
+    const manifest = readStackManifest(root);
+    const rec = readRecord(manifest.slug);
+    if (!rec)
+        throw new Error(`${manifest.slug}: the stack is not up`);
+    const s = manifest.services.find((x) => x.name === name);
+    if (!s)
+        throw new Error(`unknown service "${name}"`);
+    if (s.kind !== "start")
+        throw new Error(`${name} is a ${s.kind} step, not a service to restart`);
+    await startService(s, rec, manifest.env, true);
+    rec.lastUsedAt = now();
+    writeRecord(rec);
+}
+export function serviceLog(root, name, lines) {
+    const manifest = readStackManifest(root);
+    const s = manifest.services.find((x) => x.name === name);
+    if (!s)
+        throw new Error(`unknown service "${name}"`);
+    if (s.kind !== "start")
+        throw new Error(`${name} is a ${s.kind} step and keeps no log`);
+    return logTail(logPath(manifest.slug, name), lines);
+}
+//# sourceMappingURL=driver.js.map

package/dist/lib/stack/driver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver.js","sourceRoot":"","sources":["../../../src/lib/stack/driver.ts"],"names":[],"mappings":"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"}

package/dist/lib/stack/manifest.d.ts

@@ -0,0 +1,28 @@
+export declare const PROCESS_FILE = "DEVELOPMENT.md";
+export type ReadyProbe = {
+    kind: "tcp";
+    port: number;
+} | {
+    kind: "http";
+    url: string;
+};
+export type StackService = {
+    name: string;
+    cwd: string;
+    after: string[];
+    kind: "up" | "run" | "start";
+    command: string;
+    down?: string;
+    wipe?: string;
+    install?: string;
+    lockfile?: string;
+    ready?: ReadyProbe;
+    readyTimeoutMs: number;
+};
+export type StackManifest = {
+    root: string;
+    slug: string;
+    env: Record<string, string>;
+    services: StackService[];
+};
+export declare function readStackManifest(root: string): StackManifest;

package/dist/lib/stack/manifest.js

@@ -0,0 +1,182 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parse } from "yaml";
+// The stack manifest is the fenced ```yaml stack block of the project's
+// DEVELOPMENT.md: the dev process already lives there, so no second file kind
+// reaches the project folder. A project without the block has no managed
+// stack, and sessions keep booting and tearing down per run.
+export const PROCESS_FILE = "DEVELOPMENT.md";
+const BLOCK = /```(?:yaml|yml)[ \t]+stack[ \t]*\r?\n([\s\S]*?)```/;
+const SERVICE_KEYS = new Set([
+    "name",
+    "cwd",
+    "after",
+    "up",
+    "down",
+    "wipe",
+    "run",
+    "start",
+    "install",
+    "lockfile",
+    "ready",
+    "readyTimeoutMs",
+]);
+const NAME = /^[a-z0-9][a-z0-9-]*$/;
+// A cold Vite start after an install can sit silent for a couple of minutes
+// before its banner; three minutes covers it without hiding a real hang.
+const DEFAULT_READY_TIMEOUT_MS = 180_000;
+export function readStackManifest(root) {
+    const file = path.join(root, PROCESS_FILE);
+    if (!fs.existsSync(file)) {
+        throw new Error(`${PROCESS_FILE} not found in ${root}: run inside a project folder`);
+    }
+    const match = BLOCK.exec(fs.readFileSync(file, "utf8"));
+    if (!match) {
+        throw new Error(`${PROCESS_FILE} carries no \`\`\`yaml stack block: this project has no managed stack`);
+    }
+    const doc = parse(match[1]);
+    return {
+        root,
+        slug: path.basename(root),
+        env: parseEnv(doc),
+        services: order(parseServices(doc, root)),
+    };
+}
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function str(obj, key, where) {
+    const v = obj[key];
+    if (v === undefined)
+        return undefined;
+    if (typeof v !== "string" || v.trim() === "") {
+        throw new Error(`${where}: ${key} must be a non-empty string`);
+    }
+    return v.trim();
+}
+function parseReady(raw, where) {
+    const tcp = /^tcp:(\d{1,5})$/.exec(raw);
+    if (tcp)
+        return { kind: "tcp", port: Number(tcp[1]) };
+    if (/^https?:\/\//.test(raw))
+        return { kind: "http", url: raw };
+    throw new Error(`${where}: ready must be tcp:<port> or an http(s) url`);
+}
+function parseService(raw, root, index) {
+    const where = `services[${index}]`;
+    if (!isRecord(raw))
+        throw new Error(`${where}: must be a mapping`);
+    for (const key of Object.keys(raw)) {
+        if (!SERVICE_KEYS.has(key))
+            throw new Error(`${where}: unknown key "${key}"`);
+    }
+    const name = str(raw, "name", where);
+    if (!name || !NAME.test(name))
+        throw new Error(`${where}: name must be kebab-case`);
+    const cwd = str(raw, "cwd", `${name}`);
+    if (!cwd)
+        throw new Error(`${name}: cwd is required`);
+    const commands = ["up", "run", "start"].filter((k) => raw[k] !== undefined);
+    if (commands.length !== 1) {
+        throw new Error(`${name}: exactly one of up, run, start is required`);
+    }
+    const kind = commands[0];
+    const command = str(raw, kind, name);
+    const down = str(raw, "down", name);
+    const wipe = str(raw, "wipe", name);
+    if ((down || wipe) && kind !== "up")
+        throw new Error(`${name}: down and wipe only go with up`);
+    const install = str(raw, "install", name);
+    const lockfile = str(raw, "lockfile", name);
+    if ((install === undefined) !== (lockfile === undefined)) {
+        throw new Error(`${name}: install and lockfile go together`);
+    }
+    if (install && kind === "up")
+        throw new Error(`${name}: install does not go with up`);
+    const readyRaw = str(raw, "ready", name);
+    if (kind === "start" && !readyRaw)
+        throw new Error(`${name}: a start service needs a ready probe`);
+    if (kind === "run" && readyRaw)
+        throw new Error(`${name}: a run step takes no ready probe`);
+    const after = raw.after === undefined ? [] : raw.after;
+    if (!Array.isArray(after) || !after.every((a) => typeof a === "string")) {
+        throw new Error(`${name}: after must be a list of service names`);
+    }
+    const timeout = raw.readyTimeoutMs;
+    if (timeout !== undefined && (typeof timeout !== "number" || timeout <= 0)) {
+        throw new Error(`${name}: readyTimeoutMs must be a positive number`);
+    }
+    const absCwd = path.resolve(root, cwd);
+    return {
+        name,
+        cwd: absCwd,
+        after: after,
+        kind,
+        command,
+        ...(down ? { down } : {}),
+        ...(wipe ? { wipe } : {}),
+        ...(install ? { install } : {}),
+        ...(lockfile ? { lockfile: path.resolve(absCwd, lockfile) } : {}),
+        ...(readyRaw ? { ready: parseReady(readyRaw, name) } : {}),
+        readyTimeoutMs: typeof timeout === "number" ? timeout : DEFAULT_READY_TIMEOUT_MS,
+    };
+}
+function parseEnv(doc) {
+    if (!isRecord(doc) || doc.env === undefined)
+        return {};
+    if (!isRecord(doc.env))
+        throw new Error("stack manifest: env must be a mapping");
+    const out = {};
+    for (const [k, v] of Object.entries(doc.env)) {
+        if (!/^[A-Z][A-Z0-9_]*$/.test(k) || typeof v !== "string") {
+            throw new Error(`stack manifest: env.${k} must be an UPPER_SNAKE key with a string value`);
+        }
+        out[k] = v;
+    }
+    return out;
+}
+function parseServices(doc, root) {
+    if (!isRecord(doc) ||
+        !Array.isArray(doc.services) ||
+        doc.services.length === 0) {
+        throw new Error("stack manifest must be a mapping with a non-empty services list");
+    }
+    for (const key of Object.keys(doc)) {
+        if (key !== "services" && key !== "env") {
+            throw new Error(`stack manifest: unknown key "${key}"`);
+        }
+    }
+    const services = doc.services.map((s, i) => parseService(s, root, i));
+    const names = new Set();
+    for (const s of services) {
+        if (names.has(s.name))
+            throw new Error(`duplicate service name "${s.name}"`);
+        names.add(s.name);
+    }
+    for (const s of services) {
+        for (const dep of s.after) {
+            if (!names.has(dep))
+                throw new Error(`${s.name}: after names unknown service "${dep}"`);
+        }
+    }
+    return services;
+}
+// Stable topological order: the first service in list order whose `after`
+// are all placed goes next, one at a time, so the list order is kept wherever
+// the dependencies allow it.
+function order(services) {
+    const out = [];
+    const placed = new Set();
+    let remaining = services;
+    while (remaining.length > 0) {
+        const next = remaining.find((s) => s.after.every((a) => placed.has(a)));
+        if (!next) {
+            throw new Error(`cycle in after: ${remaining.map((s) => s.name).join(", ")}`);
+        }
+        out.push(next);
+        placed.add(next.name);
+        remaining = remaining.filter((s) => s.name !== next.name);
+    }
+    return out;
+}
+//# sourceMappingURL=manifest.js.map

package/dist/lib/stack/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../../../src/lib/stack/manifest.ts"],"names":[],"mappings":"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"}

package/dist/lib/stack/processes.d.ts

@@ -0,0 +1,11 @@
+import type { ReadyProbe } from "./manifest.js";
+export declare function runStep(command: string, cwd: string, env: Record<string, string>): void;
+export declare function spawnDetached(command: string, cwd: string, logFile: string, env: Record<string, string>): number;
+export declare function alive(pid: number): boolean;
+export declare function killGroup(pid: number): Promise<void>;
+export declare function probeOnce(probe: ReadyProbe): Promise<boolean>;
+export declare function waitReady(probe: ReadyProbe, timeoutMs: number, label: string, logFile?: string, pid?: number): Promise<void>;
+export declare function hashFile(file: string): string;
+export declare function logTail(file: string, lines?: number): string;
+export declare function composeProjects(): Set<string> | null;
+export declare function gitBranch(cwd: string): string | null;

package/dist/lib/stack/processes.js

@@ -0,0 +1,139 @@
+import { execFileSync, execSync, spawn } from "node:child_process";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import net from "node:net";
+import { setTimeout as sleep } from "node:timers/promises";
+const POLL_MS = 500;
+const PROBE_TIMEOUT_MS = 1500;
+const KILL_GRACE_MS = 10_000;
+// One-shot step (compose up, a migration, an install): the command's output
+// streams to the caller's terminal, and a non-zero exit stops the driver.
+export function runStep(command, cwd, env) {
+    execSync(command, { cwd, stdio: "inherit", env: { ...process.env, ...env } });
+}
+// Long-lived service, detached in its own process group so the driver can
+// end the whole tree later (npm and bun fork the real server), with both
+// streams appended to the service's log file.
+export function spawnDetached(command, cwd, logFile, env) {
+    const fd = fs.openSync(logFile, "a");
+    const child = spawn(command, {
+        cwd,
+        shell: true,
+        detached: true,
+        stdio: ["ignore", fd, fd],
+        env: { ...process.env, ...env },
+    });
+    fs.closeSync(fd);
+    child.unref();
+    if (child.pid === undefined)
+        throw new Error(`could not start: ${command}`);
+    return child.pid;
+}
+export function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function signalGroup(pid, signal) {
+    try {
+        process.kill(-pid, signal);
+    }
+    catch (err) {
+        // ESRCH: the group is already gone, which is the outcome wanted.
+        if (err.code !== "ESRCH")
+            throw err;
+    }
+}
+export async function killGroup(pid) {
+    signalGroup(pid, "SIGTERM");
+    const deadline = Date.now() + KILL_GRACE_MS;
+    while (alive(pid) && Date.now() < deadline)
+        await sleep(POLL_MS);
+    if (alive(pid))
+        signalGroup(pid, "SIGKILL");
+}
+function probeTcp(port) {
+    return new Promise((resolve) => {
+        const socket = net.createConnection({
+            port,
+            host: "localhost",
+            autoSelectFamily: true,
+        });
+        const done = (ok) => {
+            socket.destroy();
+            resolve(ok);
+        };
+        socket.setTimeout(PROBE_TIMEOUT_MS, () => done(false));
+        socket.once("connect", () => done(true));
+        socket.once("error", () => done(false));
+    });
+}
+async function probeHttp(url) {
+    try {
+        const res = await fetch(url, {
+            signal: AbortSignal.timeout(PROBE_TIMEOUT_MS),
+        });
+        return res.status < 500;
+    }
+    catch {
+        return false;
+    }
+}
+export function probeOnce(probe) {
+    return probe.kind === "tcp" ? probeTcp(probe.port) : probeHttp(probe.url);
+}
+export async function waitReady(probe, timeoutMs, label, logFile, pid) {
+    const deadline = Date.now() + timeoutMs;
+    const tail = () => logFile ? `\n--- ${logFile} ---\n${logTail(logFile)}` : "";
+    while (Date.now() < deadline) {
+        if (await probeOnce(probe))
+            return;
+        if (pid !== undefined && !alive(pid)) {
+            throw new Error(`${label}: exited before answering its ready probe${tail()}`);
+        }
+        await sleep(POLL_MS);
+    }
+    throw new Error(`${label}: not ready after ${Math.round(timeoutMs / 1000)}s${tail()}`);
+}
+export function hashFile(file) {
+    return crypto
+        .createHash("sha256")
+        .update(fs.readFileSync(file))
+        .digest("hex");
+}
+export function logTail(file, lines = 40) {
+    if (!fs.existsSync(file))
+        return "";
+    return fs.readFileSync(file, "utf8").split("\n").slice(-lines).join("\n");
+}
+// Compose project labels of the running containers; null when Docker is
+// absent or down (then nothing is recorded, and nothing is exempted).
+export function composeProjects() {
+    try {
+        const out = execFileSync("docker", ["ps", "--format", '{{.Label "com.docker.compose.project"}}'], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+        return new Set(out
+            .split("\n")
+            .map((l) => l.trim())
+            .filter((l) => l !== ""));
+    }
+    catch {
+        return null;
+    }
+}
+export function gitBranch(cwd) {
+    try {
+        return execFileSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+            cwd,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=processes.js.map

package/dist/lib/stack/processes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"processes.js","sourceRoot":"","sources":["../../../src/lib/stack/processes.ts"],"names":[],"mappings":"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"}

package/dist/lib/stack/registry.d.ts

@@ -0,0 +1,24 @@
+export declare const STACKS_DIR: string;
+export type ServiceRecord = {
+    pid: number | null;
+    startedAt: string;
+};
+export type StackRecord = {
+    slug: string;
+    root: string;
+    branch: string | null;
+    startedAt: string;
+    lastUsedAt: string;
+    services: Record<string, ServiceRecord>;
+    ups: Record<string, {
+        owned: boolean;
+    }>;
+    installs: Record<string, string>;
+    composeProjects: string[];
+};
+export declare function logDir(slug: string): string;
+export declare function logPath(slug: string, service: string): string;
+export declare function readRecord(slug: string): StackRecord | null;
+export declare function writeRecord(rec: StackRecord): void;
+export declare function removeRecord(slug: string): void;
+export declare function listRecords(): StackRecord[];