@yadurajfleetos/cli 0.17.2 → 0.18.0

package/dist/commands/services.js

@@ -6,6 +6,7 @@ import { task, glyph } from '../ui.js';
 import { withLadder } from '../ladder.js';
 import { ask, canPrompt, confirm, selectOrThrow } from '../prompt.js';
 import { DEPLOY_STEPS, follow, phaseWalker, } from '../progress.js';
+import { planFromDiscovery, renderPlan, toAssistPlan } from '../deployment-plan.js';
 import { planFromManifest, projectNameFor } from '../plan.js';
 import { uploadContext, humanBytes } from '../archive.js';
 import { localSource } from '../source.js';
@@ -275,7 +276,16 @@ export const deployCommand = {
                 onUnavailable: () => ladder.note(c.dim('live progress unavailable; continuing with the deploy request')),
             });
             try {
-                const result = (await request('POST', `/services/${service.id}/deploy`, { body: { gitSha, contextId } })).body;
+                const result = (await request('POST', `/services/${service.id}/deploy`, {
+                    body: {
+                        gitSha,
+                        contextId,
+                        // Was in KNOWN_FLAGS and read by nothing, so `--node` was
+                        // accepted and ignored and the scheduler picked whatever
+                        // scored highest.
+                        ...(typeof flags.node === 'string' ? { node: flags.node } : {}),
+                    },
+                })).body;
                 walker.finish(`scheduled onto ${result.placedOn.name}`);
                 return result;
             }
@@ -449,36 +459,90 @@ export const logsCommand = {
     },
 };
 /**
- * The node to pin a database to, when there is only one it could be.
+ * The fleet's nodes, fetched once per process.
  *
- * A database has to name the node holding its data — that is the one decision
- * Fleet will not make for you, because moving a database moves its disk. But
- * on a fleet with a single node there is no decision to make, and writing
- * CHANGE_ME there meant `init` produced a manifest whose next command fails:
+ * `init` asks for a node for every database it found, and a repository with
+ * Postgres and Redis asked twice for a list that cannot change between the two
+ * questions.
+ */
+let nodeCache = null;
+async function fleetNodes(flags) {
+    if (nodeCache)
+        return nodeCache;
+    const fleetId = await requireFleet(typeof flags.fleet === 'string' ? flags.fleet : undefined);
+    const { body } = await request('GET', `/fleets/${fleetId}/nodes`);
+    nodeCache = body.nodes;
+    return nodeCache;
+}
+/** Free disk in MB, from whichever pair of numbers the agent reported. */
+function freeDiskMb(n) {
+    const used = n.telemetry?.diskUsedMb;
+    const total = n.telemetry?.diskTotalMb;
+    if (typeof used === 'number' && typeof total === 'number' && total > 0)
+        return total - used;
+    // node.diskMb is free space already. Falling back to it rather than
+    // inventing a capacity: an unavailable metric stays unavailable.
+    return typeof n.diskMb === 'number' ? n.diskMb : undefined;
+}
+/**
+ * Which node should hold a database's data.
  *
- *     error  The manifest names nodes that are not in this fleet
- *       services.db.node: no node named "CHANGE_ME" in this fleet
+ * This replaces a function that answered only when the fleet had exactly one
+ * node and gave up otherwise — writing `node: CHANGE_ME` into a file whose very
+ * next command then failed on it. A fleet with two nodes is the common case,
+ * not the exceptional one, so "I cannot choose" was the usual answer.
  *
- * Best effort, and quiet about it. `init` otherwise needs no control plane at
- * all — it reads a directory — so a missing session, an unreachable server or
- * a fleet with several nodes all fall back to the placeholder rather than
- * turning a local command into one that requires the network.
+ * Ranked on what a database actually needs from a machine: it must be able to
+ * hold the data, so free disk decides, and free RAM breaks ties. Metrics the
+ * agent did not report are left out of the comparison rather than defaulted —
+ * a node that reports no disk is not thereby a node with no disk.
+ *
+ * Returns undefined only when the fleet has no nodes at all, which is the one
+ * case no amount of scoring can fix.
  */
-async function theOnlyNode(flags) {
+export async function pickNodeForData(flags, what) {
+    let nodes;
     try {
-        const fleetId = await requireFleet(typeof flags.fleet === 'string' ? flags.fleet : undefined);
-        const { body } = await request('GET', `/fleets/${fleetId}/nodes`);
-        // Offline is fine: a node that is down still holds its disk, and that is
-        // what pinning is about. Only an empty fleet has nothing to choose.
-        if (body.nodes.length !== 1)
-            return undefined;
-        const only = body.nodes[0].name;
-        console.log(c.dim(`  · pinned the database to ${only}, the only node in this fleet`));
-        return only;
+        nodes = await fleetNodes(flags);
     }
     catch {
         return undefined;
     }
+    if (!nodes.length)
+        return undefined;
+    // An explicit --node is the operator's decision and outranks any scoring.
+    // It is still checked, because a typo silently ignored is how the wrong
+    // machine ends up holding the data.
+    const explicit = typeof flags.node === 'string' ? flags.node : undefined;
+    if (explicit) {
+        const match = nodes.find((n) => n.name === explicit);
+        if (!match) {
+            throw new CliError(`No node called "${explicit}" in this fleet. Known: ${nodes.map((n) => n.name).join(', ')}.`, EXIT.usage);
+        }
+        return { node: match.name, why: 'you named it with --node' };
+    }
+    if (nodes.length === 1) {
+        return { node: nodes[0].name, why: 'the only node in this fleet' };
+    }
+    // Offline is not disqualifying: a node that is down still holds its disk,
+    // and pinning is about where the data lives. It is a tie-breaker, not a gate.
+    const ranked = [...nodes].sort((a, b) => {
+        const live = Number(b.live ?? false) - Number(a.live ?? false);
+        if (live)
+            return live;
+        const disk = (freeDiskMb(b) ?? -1) - (freeDiskMb(a) ?? -1);
+        if (disk)
+            return disk;
+        return (b.ramMb ?? 0) - (a.ramMb ?? 0);
+    });
+    const best = ranked[0];
+    const disk = freeDiskMb(best);
+    const reasons = [
+        disk !== undefined ? `${Math.round(disk / 1024)}GB free` : 'free disk not reported',
+        best.live ? 'reporting' : 'not reporting',
+    ];
+    console.log(c.dim(`  · ${what} pinned to ${best.name} — ${reasons.join(', ')}; change it before applying if that is wrong`));
+    return { node: best.name, why: reasons.join(', ') };
 }
 /**
  * A second opinion on the draft, when --ai is given.
@@ -492,7 +556,16 @@ async function theOnlyNode(flags) {
  * appeared with different ports and no explanation is worse than one with a
  * mistake in it -- at least the mistake is yours to find.
  */
-async function reviewed(draft, flags, services) {
+async function reviewed(draft, flags, services, 
+/**
+ * What discovery already settled.
+ *
+ * Sent so the model is told the facts rather than left to read them back out
+ * of the draft it is being asked to correct — a reviewer shown only YAML
+ * treats every line as a proposal, including the ones deterministic code
+ * already decided and will re-check afterwards regardless.
+ */
+plan) {
     const { repoMap } = await import('../repomap.js');
     const fleetId = await requireFleet(typeof flags.fleet === 'string' ? flags.fleet : undefined);
     // The second pass is a different, smaller question.
@@ -507,6 +580,7 @@ async function reviewed(draft, flags, services) {
         body: {
             draft: base,
             repoMap: map,
+            ...(plan ? { plan } : {}),
             ...(answers ? { answers } : {}),
             ...(parts ? { parts } : {}),
         },
@@ -686,14 +760,41 @@ export const initCommand = {
         const { discover, manifestFromDiscovery } = await import('../discover.js');
         const found = await discover();
         if (found.services.length > 1 || found.databases.length) {
+            // Resolved before the plan is built, so the plan can state where the
+            // data is going instead of describing a decision still to be made.
+            const chosen = found.databases.length
+                ? await pickNodeForData(flags, found.databases.map((d) => d.name).join(' and '))
+                : undefined;
             const drafted = manifestFromDiscovery(found, {
                 fleet: typeof flags.fleet === 'string' ? flags.fleet : undefined,
-                node: (typeof flags.node === 'string' ? flags.node : undefined) ??
-                    (found.databases.length ? await theOnlyNode(flags) : undefined),
+                // Resolved here, not deferred into the file. A database needs a node
+                // and `pickNodeForData` answers for any fleet that has one, so the
+                // placeholder is reachable only when the fleet has no nodes at all.
+                node: chosen?.node,
+            });
+            // Said before the file appears, not after. Everything here is a
+            // projection of what discovery already established — nothing is
+            // re-detected, and nothing the discovery could not settle is filled in.
+            const plan = planFromDiscovery(found, {
+                project: projectNameFor(process.cwd()),
+                ...(chosen ? { node: chosen.node, nodeWhy: chosen.why } : {}),
             });
+            for (const line of renderPlan(plan)) {
+                console.log(line ? c.dim(line) : '');
+            }
+            console.log('');
+            // Asked before anything is written, because writing is the side effect.
+            // `confirm` returns its `ifNoTerminal` answer when there is no tty, so a
+            // scripted `fleet init` keeps working exactly as it did.
+            if (!flags.yes &&
+                !flags.y &&
+                !(await confirm('Write this manifest?', { default: true, ifNoTerminal: true }))) {
+                console.log(c.dim('Nothing was written.'));
+                return;
+            }
             const questions = drafted.questions;
             const manifest = flags.ai
-                ? await reviewed(drafted.manifest, flags, found.services.map((s) => ({ name: s.name, dir: s.dir })))
+                ? await reviewed(drafted.manifest, flags, found.services.map((s) => ({ name: s.name, dir: s.dir })), toAssistPlan(plan))
                 : drafted.manifest;
             await writeFile(path, manifest);
             console.log(`${c.green('created')} ${path}`);
@@ -832,7 +933,7 @@ export const importCommand = {
                 // a manifest that must name a node, and on a one-node fleet there is
                 // nothing to choose. Without this, import wrote a placeholder and the
                 // very next command failed on it.
-                node: (typeof flags.node === 'string' ? flags.node : undefined) ?? (await theOnlyNode(flags)),
+                node: (await pickNodeForData(flags, 'the database'))?.node,
             });
         }
         catch (err) {

package/dist/commands/up.js

@@ -99,6 +99,7 @@ export const upCommand = {
                 gitSha,
                 buildContext: buildContexts.get(service.name),
                 wait: !flags['no-wait'],
+                ...(typeof flags.node === 'string' ? { node: flags.node } : {}),
                 rootDir: typeof flags.file === 'string' ? dirname(flags.file) : rootDir,
             });
             deployed.push({ service, url });
@@ -137,7 +138,7 @@ async function deployOne(service, opts) {
         });
         try {
             const result = (await request('POST', `/services/${service.id}/deploy`, {
-                body: { gitSha: opts.gitSha, contextId },
+                body: { gitSha: opts.gitSha, contextId, ...(opts.node ? { node: opts.node } : {}) },
             })).body;
             // Deliberately not walker.finish().
             //
@@ -189,8 +190,12 @@ async function deployOne(service, opts) {
                 const line = await request('GET', `/services/${service.id}/progress`)
                     .then((r) => r.body)
                     .catch(() => null);
-                if (line && ['queued', 'building', 'pushing'].includes(line.status)) {
-                    const parts = [line.status];
+                if (line && ['queued', 'building', 'pushing', 'deploying'].includes(line.status)) {
+                    // The agent's own stage once the image leaves the control plane.
+                    // Before this, everything from "pull" to "health check passed" was
+                    // one line reading "waiting for the container", which is why a
+                    // 477-second deploy was indistinguishable from a hang.
+                    const parts = [line.phase ?? line.status];
                     if (line.step && line.ofSteps)
                         parts.push(`${line.step}/${line.ofSteps}`);
                     if (line.platform)

package/dist/deployment-plan.js

@@ -0,0 +1,117 @@
+/**
+ * Project the discovery model onto the plan.
+ *
+ * Pure, and takes an already-resolved node rather than looking one up: node
+ * selection talks to the control plane and belongs to the caller, which leaves
+ * this testable without a fleet.
+ */
+export function planFromDiscovery(discovery, opts) {
+    const entries = [];
+    for (const svc of discovery.services) {
+        entries.push({
+            name: svc.name,
+            kind: 'service',
+            what: svc.detection.label,
+            ramMb: svc.ramMb,
+            // Discovery sizes a GPU service differently and gives everything else one
+            // default. That is a recommendation, not a measurement, and labelling it
+            // otherwise would be the invented precision this plan exists to avoid.
+            ramFrom: 'recommended',
+            placement: 'flexible',
+            // The engines this service's OWN dependencies imply. Discovery is already
+            // careful here — a frontend beside a backend must not claim to use the
+            // database — so this is a projection, not a second inference.
+            dependsOn: discovery.databases.filter((d) => svc.engines.includes(d.engine)).map((d) => d.name),
+            persistent: false,
+        });
+    }
+    for (const db of discovery.databases) {
+        entries.push({
+            name: db.name,
+            kind: 'database',
+            what: db.engine,
+            // Matches what `manifestFromDiscovery` writes, so the plan cannot
+            // describe a manifest different from the one produced.
+            ramMb: 512,
+            ramFrom: 'recommended',
+            placement: 'pinned',
+            ...(opts.node ? { node: opts.node } : {}),
+            ...(opts.nodeWhy ? { nodeWhy: opts.nodeWhy } : {}),
+            dependsOn: [],
+            // A database holds data by definition; that is why it is pinned at all.
+            persistent: true,
+        });
+    }
+    const limits = [];
+    if (discovery.databases.length) {
+        // Answered honestly rather than invented. `volume:` names a volume and
+        // `backup:` schedules a copy; neither carries a size, so a plan printing
+        // "20 GB" would describe a field the manifest cannot hold.
+        limits.push('storage size: unknown — a manifest can name a volume and a backup schedule, but has no field for its size');
+    }
+    return {
+        project: opts.project,
+        entries,
+        secrets: [...new Set(discovery.services.flatMap((s) => s.secrets))].sort(),
+        totalRamMb: entries.reduce((sum, e) => sum + e.ramMb, 0),
+        limits,
+    };
+}
+const size = (mb) => mb >= 1024 ? `${(mb / 1024).toFixed(mb % 1024 === 0 ? 0 : 2)} GiB` : `${mb} MiB`;
+/**
+ * The plan as lines, for the terminal.
+ *
+ * Returns them rather than printing, so a test can read exactly what a user
+ * would see.
+ */
+export function renderPlan(plan) {
+    const out = [`Deployment plan · ${plan.project}`];
+    const services = plan.entries.filter((e) => e.kind === 'service');
+    const databases = plan.entries.filter((e) => e.kind === 'database');
+    if (services.length) {
+        out.push('', 'Services');
+        for (const s of services) {
+            out.push(`  ${s.name}  ${s.what} · ${size(s.ramMb)} · ${s.placement}`);
+            if (s.dependsOn.length)
+                out.push(`    uses ${s.dependsOn.join(', ')}`);
+        }
+    }
+    if (databases.length) {
+        out.push('', 'Databases');
+        for (const d of databases) {
+            // An unresolved node is stated, not hidden. It is the one thing that
+            // stops the manifest deploying, and the reader should meet it here
+            // rather than three commands later.
+            const where = d.node ? `→ ${d.node}` : '→ no node chosen yet';
+            out.push(`  ${d.name}  ${d.what} · ${size(d.ramMb)} · pinned ${where}`);
+            if (d.nodeWhy)
+                out.push(`    ${d.nodeWhy}`);
+        }
+    }
+    if (plan.secrets.length) {
+        out.push('', `Secrets · ${plan.secrets.length} required`);
+        out.push(`  ${plan.secrets.join(', ')}`);
+        out.push('  values are never read or written into the manifest');
+    }
+    out.push('', `Memory · ${size(plan.totalRamMb)} across ${plan.entries.length} containers`);
+    out.push('  every figure is a starting point, not a measurement');
+    for (const limit of plan.limits)
+        out.push(`  ${limit}`);
+    return out;
+}
+export function toAssistPlan(plan) {
+    return {
+        project: plan.project,
+        entries: plan.entries.map((e) => ({
+            name: e.name,
+            kind: e.kind,
+            what: e.what,
+            ramMb: e.ramMb,
+            placement: e.placement,
+            ...(e.node ? { node: e.node } : {}),
+            dependsOn: e.dependsOn,
+            persistent: e.persistent,
+        })),
+        secrets: plan.secrets,
+    };
+}

package/dist/index.js

@@ -18,6 +18,7 @@ const GROUPS = [
             ['up [service]', 'Deploy the whole fleet.yaml, in dependency order'],
             ['init', 'Read the repository — monorepo, databases, secrets — and write a fleet.yaml'],
             ['init --ai', 'The same, then have the control plane review the draft against the repository'],
+            ['init --node <name>', 'Pin discovered databases to a specific node instead of the best-scoring one'],
             ['import [file]', 'Convert a docker-compose.yml into a fleet.yaml'],
             ['config show', 'Show the saved control plane and selected fleet'],
             ['use <fleet>', 'Select the default fleet for later commands'],
@@ -73,6 +74,9 @@ const GROUPS = [
 ];
 const OPTIONS = [
     ['--fleet <id>', 'Operate on a specific fleet'],
+    // Documented because it silently did nothing on `up` and `deploy` for a long
+    // time, and a flag that validates but is ignored is worse than one that errors.
+    ['--node <name>', 'Deploy onto this node, or say why the service cannot go there'],
     ['--api <url>', 'Control plane URL (default: saved profile)'],
     ['--json', 'Machine-readable output on stdout'],
     ['--plan, --dry-run', 'Show the deploy placement plan without changing anything'],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yadurajfleetos/cli",
-  "version": "0.17.2",
+  "version": "0.18.0",
   "description": "Fleet OS command-line interface for deploying and orchestrating services on user-owned hardware",
   "type": "module",
   "license": "MIT",