@yadurajfleetos/cli 0.8.0 → 0.9.0

package/dist/args.js

@@ -25,3 +25,62 @@ export function parseArgs(argv) {
     }
     return { positional, flags };
 }
+/**
+ * Every flag this CLI reads, anywhere.
+ *
+ * An unknown flag used to be accepted and thrown away, which is how three
+ * separate features looked broken in one day: `apply --dry-run` applied,
+ * `init --ai` skipped the review, and both read as "the feature does not
+ * work" rather than "this build does not have it". A CLI that ignores what
+ * you typed is worse than one that refuses it — the refusal is a sentence,
+ * the silence is an afternoon.
+ *
+ * One list rather than a spec per command. It catches the case that actually
+ * bites — a flag that does not exist in the installed version, or a typo —
+ * without threading a declaration through twenty commands. It does not catch
+ * a real flag used on the wrong command; that is a smaller wrong than this.
+ */
+export const KNOWN_FLAGS = new Set([
+    // global
+    'fleet', 'api', 'json', 'yes', 'y', 'help', 'h', 'version', 'v', 'no-wait',
+    'plan', 'dry-run', 'force',
+    // per command
+    'ai', 'all', 'channel', 'deploy', 'email', 'events', 'f', 'follow', 'limit',
+    'name', 'node', 'only', 'out', 'password', 'secret', 'service', 'sha',
+    'since', 'terminal', 'to', 'token', 'url',
+]);
+/** The closest known flag to a mistyped one, or null when nothing is close. */
+export function nearestFlag(name) {
+    if (KNOWN_FLAGS.has(name))
+        return name;
+    // A prefix relationship first, because the common mistakes are a flag with
+    // something stuck on the end and a flag typed short. `--ai-typo` should
+    // suggest `--ai`, which a pure edit distance rates as five changes away and
+    // therefore no relation at all.
+    let prefixBest = null;
+    for (const known of KNOWN_FLAGS) {
+        if (known.length < 2)
+            continue;
+        if (!name.startsWith(known) && !known.startsWith(name))
+            continue;
+        if (!prefixBest || Math.abs(known.length - name.length) < Math.abs(prefixBest.length - name.length)) {
+            prefixBest = known;
+        }
+    }
+    if (prefixBest)
+        return prefixBest;
+    // Otherwise a transposition or a wrong letter: same length, few differences.
+    let best = null;
+    for (const known of KNOWN_FLAGS) {
+        if (Math.abs(known.length - name.length) > 1)
+            continue;
+        let wrong = Math.abs(known.length - name.length);
+        for (let i = 0; i < Math.min(known.length, name.length); i++) {
+            if (known[i] !== name[i])
+                wrong++;
+        }
+        if (!best || wrong < best.wrong)
+            best = { flag: known, wrong };
+    }
+    return best && best.wrong <= 2 ? best.flag : null;
+}

package/dist/commands/services.js

@@ -415,6 +415,38 @@ export const logsCommand = {
         }
     },
 };
+/**
+ * The node to pin a database to, when there is only one it could be.
+ *
+ * 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:
+ *
+ *     error  The manifest names nodes that are not in this fleet
+ *       services.db.node: no node named "CHANGE_ME" in this fleet
+ *
+ * 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.
+ */
+async function theOnlyNode(flags) {
+    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;
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * A second opinion on the draft, when --ai is given.
  *
@@ -430,12 +462,14 @@ export const logsCommand = {
 async function reviewed(draft, flags) {
     const { repoMap } = await import('../repomap.js');
     const fleetId = await requireFleet(typeof flags.fleet === 'string' ? flags.fleet : undefined);
+    const review = (map, answers) => task(answers ? 'applying your answers' : 'reading the repository for a second opinion', async () => request('POST', `/fleets/${fleetId}/manifest/assist`, {
+        body: { draft, repoMap: map, ...(answers ? { answers } : {}) },
+    }), { done: () => (answers ? 'done' : 'reviewed') });
+    let map;
     let out;
     try {
-        const map = await repoMap();
-        out = (await task('reading the repository for a second opinion', async () => request('POST', `/fleets/${fleetId}/manifest/assist`, {
-            body: { draft, repoMap: map },
-        }), { done: () => 'reviewed' })).body;
+        map = await repoMap();
+        out = (await review(map)).body;
     }
     catch (err) {
         console.log(`${glyph.warn} ${c.yellow('review skipped')}  ${err instanceof Error ? err.message : 'the control plane could not be reached'}`);
@@ -454,16 +488,72 @@ async function reviewed(draft, flags) {
         console.log(`${glyph.warn} ${c.yellow('kept the draft')}  ${out.reason}`);
         return draft;
     }
-    if (!out.changed) {
-        console.log(`${glyph.ok} ${c.green('reviewed')}  ${c.dim('nothing to change')}`);
-        return out.manifest;
-    }
-    console.log(`${glyph.ok} ${c.green('reviewed')}  ${c.dim(out.model)}`);
+    // Questions are asked whether or not anything changed. A model that could
+    // not settle something leaves the draft exactly as it found it and asks —
+    // returning early on "nothing to change" swallowed precisely the case the
+    // questions exist for.
+    console.log(`${glyph.ok} ${c.green('reviewed')}  ${c.dim(out.changed ? out.model : 'nothing to change')}`);
     for (const note of out.notes)
         console.log(c.dim(`  · ${note}`));
+    // Anything the evidence could not settle is asked rather than guessed.
+    //
+    // Only when there is somebody to ask: piped into a script, or run with
+    // --yes, the questions are printed as what was assumed instead. A command
+    // that blocks on a prompt nobody can answer is worse than one that decides.
+    const answered = await answerQuestions(out.questions, flags);
+    if (answered) {
+        try {
+            const second = (await review(map, answered)).body;
+            if (second.status === 'ok') {
+                for (const note of second.notes)
+                    console.log(c.dim(`  · ${note}`));
+                console.log(c.dim(`  ${second.usage.used}/${second.usage.limit} reviews used today`));
+                return second.manifest;
+            }
+            // The second pass failing is not a reason to lose the first one.
+            console.log(`${glyph.warn} ${c.yellow('kept the first answer')}  ${'reason' in second ? second.reason : 'the follow-up did not come back'}`);
+        }
+        catch {
+            console.log(`${glyph.warn} ${c.yellow('kept the first answer')}  the follow-up could not be sent`);
+        }
+    }
     console.log(c.dim(`  ${out.usage.used}/${out.usage.limit} reviews used today`));
     return out.manifest;
 }
+/**
+ * Put the model's open questions to the person running the command.
+ *
+ * Returns null when there is nothing to ask, or nobody to ask — the answers
+ * are then left to the manifest as it stands, and what was assumed is printed
+ * so the omission is visible rather than silent.
+ */
+async function answerQuestions(questions, flags) {
+    if (!questions.length)
+        return null;
+    const { canPrompt, select } = await import('../prompt.js');
+    if (flags.yes || !canPrompt()) {
+        console.log(c.dim('  · not asking (--yes or no terminal); left as generated:'));
+        for (const q of questions)
+            console.log(c.dim(`    ? ${q.ask}`));
+        return null;
+    }
+    const answers = {};
+    for (const q of questions) {
+        console.log('');
+        if (q.why)
+            console.log(c.dim(`  ${q.why}`));
+        answers[q.id] = await select(q.ask, 
+        // "Leave it as generated" last and always present: a question with no
+        // way to decline is a demand, and the draft is a legitimate answer.
+        [
+            ...q.options.map((o) => ({ label: o.label, value: o.value })),
+            { label: 'leave it as generated', value: '' },
+        ]);
+        if (!answers[q.id])
+            delete answers[q.id];
+    }
+    return Object.keys(answers).length ? answers : null;
+}
 export const initCommand = {
     async run(args, flags) {
         const { detect, manifestTemplate } = await import('../detect.js');
@@ -489,7 +579,8 @@ export const initCommand = {
         if (found.services.length > 1 || found.databases.length) {
             const drafted = manifestFromDiscovery(found, {
                 fleet: typeof flags.fleet === 'string' ? flags.fleet : undefined,
-                node: typeof flags.node === 'string' ? flags.node : undefined,
+                node: (typeof flags.node === 'string' ? flags.node : undefined) ??
+                    (found.databases.length ? await theOnlyNode(flags) : undefined),
             });
             const questions = drafted.questions;
             const manifest = flags.ai ? await reviewed(drafted.manifest, flags) : drafted.manifest;
@@ -626,7 +717,11 @@ export const importCommand = {
         try {
             result = composeToFleet(text, {
                 fleet: typeof flags.fleet === 'string' ? flags.fleet : undefined,
-                node: typeof flags.node === 'string' ? flags.node : undefined,
+                // Same reasoning as init: a compose file that runs a database becomes
+                // 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)),
             });
         }
         catch (err) {

package/dist/compose.js

@@ -1,5 +1,6 @@
 import { parse as parseYaml } from 'yaml';
 import { safeDatabaseName } from './dbnames.js';
+import { injectedUrl, pointsAt } from './dburl.js';
 /** Images Fleet manages as databases rather than as plain containers. */
 const ENGINE_IMAGES = {
     postgres: 'postgres',
@@ -196,6 +197,8 @@ export function composeToFleet(source, opts = {}) {
     /** Compose name -> the name the database is declared under, which differs
         whenever the compose name would collide with its engine's own env vars. */
     const dbNames = new Map();
+    /** Compose name -> engine, so a connection string can be rewritten to it. */
+    const dbEngines = new Map();
     const takenDbNames = new Set();
     // Databases first, so a service's `uses` can reference one by name.
     for (const [name, raw] of Object.entries(servicesRaw)) {
@@ -209,6 +212,7 @@ export function composeToFleet(source, opts = {}) {
         // service declared before it in the file still has to point at the name it
         // ends up with, and the main loop would not know it yet.
         dbNames.set(name, safeDatabaseName(name, engine, takenDbNames));
+        dbEngines.set(name, engine);
     }
     for (const [name, raw] of Object.entries(servicesRaw)) {
         const svc = (asRecord(raw) ?? {});
@@ -294,6 +298,25 @@ export function composeToFleet(source, opts = {}) {
                 notes.push(`${name}: dropped env key "${k}" — not a usable variable name.`);
                 continue;
             }
+            // A connection string aimed at a service that just became a managed
+            // database is rewritten to the URL Fleet will actually inject.
+            //
+            // Left alone it goes one of two wrong ways: copied verbatim, so the app
+            // dials `mongo:27017` which no longer exists, or swept into `secrets`
+            // because the key matches _URI, so the user is asked to supply a value
+            // Fleet already knows. Both deploy cleanly and fail to connect, which is
+            // the worst kind of wrong — nothing in the manifest looks suspicious.
+            const target = [...dbNames.entries()].find(([composeName]) => pointsAt(v, composeName));
+            if (target) {
+                const [composeName, fleetName] = target;
+                const engine = dbEngines.get(composeName);
+                const url = engine ? injectedUrl(fleetName, engine) : null;
+                if (url) {
+                    plain.push([k, url]);
+                    notes.push(`${name}: ${k} now points at the managed ${engine} — it named the compose service "${composeName}", which Fleet runs as "${fleetName}" with a password it generates.`);
+                    continue;
+                }
+            }
             const unresolved = v === '' || /^\$\{?[A-Za-z_]/.test(v);
             if (SECRET_HINT.test(k) || unresolved)
                 secrets.push(k);

package/dist/dburl.js

@@ -0,0 +1,54 @@
+/**
+ * The connection URL Fleet will inject for a managed database.
+ *
+ * `uses: [db]` gives a service DATABASE_URL and friends. An imported compose
+ * file usually has its own variable for the same thing — MONGODB_URI,
+ * DATABASE_URL, REDIS_URL — pointing at the compose service that just became a
+ * managed database. Left alone that variable is either copied verbatim, so the
+ * app dials a host that no longer exists, or moved to `secrets`, so the user is
+ * asked to supply a value Fleet already knows. Both end in an app that deploys
+ * and cannot reach its database.
+ *
+ * This is deliberately a copy of what the control plane computes, because the
+ * CLI cannot import it — they are separate packages, and the CLI has to work
+ * against a control plane it did not build. The copy is kept honest by a test
+ * in the control plane that reads this file and fails when the two disagree,
+ * which is the only thing that makes duplicating it acceptable.
+ */
+/** Mirrors ENGINES in control-plane/src/manifest/databases.ts. */
+export const ENGINE_WIRE = {
+    postgres: { scheme: 'postgres', port: 5432, defaultUser: 'postgres', usesPassword: true, usesDatabase: true },
+    mysql: { scheme: 'mysql', port: 3306, defaultUser: 'app', usesPassword: true, usesDatabase: true },
+    mariadb: { scheme: 'mysql', port: 3306, defaultUser: 'app', usesPassword: true, usesDatabase: true },
+    redis: { scheme: 'redis', port: 6379, defaultUser: '', usesPassword: false, usesDatabase: false },
+    mongo: { scheme: 'mongodb', port: 27017, defaultUser: 'app', usesPassword: true, usesDatabase: true },
+};
+/** Mirrors passwordRefFor: the secret name a database's password lives under. */
+export const passwordRefFor = (name) => `${name.toUpperCase().replace(/[^A-Z0-9]+/g, '_')}_PASSWORD`;
+/**
+ * The URL a service will see, written the way the manifest can carry it.
+ *
+ * The password is a `${secret:NAME}` reference rather than a value: it is
+ * generated by the control plane and never known here, and a manifest is a
+ * file people commit.
+ */
+export function injectedUrl(dbName, engine) {
+    const spec = ENGINE_WIRE[engine];
+    if (!spec)
+        return null;
+    const auth = spec.usesPassword
+        ? `${encodeURIComponent(spec.defaultUser)}:\${secret:${passwordRefFor(dbName)}}@`
+        : '';
+    // `database` defaults to the declaration's own name, and the host is that
+    // same name: containers resolve each other by service name on the node.
+    const path = spec.usesDatabase ? `/${dbName}` : '';
+    return `${spec.scheme}://${auth}${dbName}:${spec.port}${path}`;
+}
+/** Does this value look like a connection URL aimed at `host`? */
+export function pointsAt(value, host) {
+    // Scheme-relative on purpose: an app may hold a mongodb+srv:// or a
+    // postgresql:// where Fleet writes postgres://, and the host is what says
+    // this is the same database rather than an unrelated service.
+    const match = value.match(/^[a-z][a-z0-9+.-]*:\/\/(?:[^@/]*@)?([^:/?#]+)/i);
+    return match?.[1]?.toLowerCase() === host.toLowerCase();
+}

package/dist/index.js

@@ -5,7 +5,7 @@ import { CliError, EXIT } from './api.js';
 import { c } from './render.js';
 import { banner } from './mark.js';
 import { commands } from './commands/index.js';
-import { parseArgs } from './args.js';
+import { parseArgs, KNOWN_FLAGS, nearestFlag } from './args.js';
 export { parseArgs };
 /**
  * Grouped by the order an operator meets them, not alphabetically: the first
@@ -111,6 +111,17 @@ async function main() {
         // A bare `fleet` is someone asking what this is, not a malformed command.
         process.exit(EXIT.ok);
     }
+    // A flag this build does not know is refused, not ignored. Checked after
+    // --help so `fleet --oops --help` still explains itself.
+    for (const flag of Object.keys(flags)) {
+        if (KNOWN_FLAGS.has(flag))
+            continue;
+        const near = nearestFlag(flag);
+        console.error(`${c.red('unknown option')} "--${flag}"` +
+            (near ? `\n  did you mean: --${near}?` : '') +
+            `\n  ${c.dim('if it is a newer flag, upgrade: npm i -g @yadurajfleetos/cli@latest')}`);
+        process.exit(EXIT.usage);
+    }
     const command = commands[name];
     if (!command) {
         const near = Object.keys(commands).filter((k) => k.startsWith(name[0] ?? ''));

package/package.json

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