vibecarbon 0.1.0

package/src/lib/cli/help.js

@@ -0,0 +1,129 @@
+/**
+ * Shared help-text renderer for vibecarbon commands.
+ *
+ * Each command exports a `CommandSpec` (see `parse-flags.js` for the
+ * type) and this renderer produces the human help body from it. One
+ * authoritative source for usage info means flags can't drift between
+ * the parser and the help output the way they did when each command
+ * hand-rolled both — a common failure mode in the old code where a
+ * flag would be parsed but missing from `--help`, or vice-versa.
+ *
+ * The output style mirrors the existing tone: bold section headers,
+ * cyan flag/value names, dim descriptions. Sections are skipped
+ * silently when their data is empty (no flags? no FLAGS section).
+ *
+ * Vibecarbon is single-dash-only — flag names render as `-name`,
+ * never `--name`. See memory:feedback_cli_single_dash_flags.
+ */
+
+import { c } from '../colors.js';
+
+/**
+ * @typedef {object} HelpExample
+ * @property {string} command - the literal invocation (without
+ *   the leading `$ ` shell prompt).
+ * @property {string} [description] - one-line context shown above
+ *   the command in dim text.
+ *
+ * @typedef {import('./parse-flags.js').CommandSpec & {
+ *   examples?: HelpExample[],
+ *   description?: string,
+ * }} HelpSpec
+ */
+
+/**
+ * Render a command's help body. Returns a string ending in a newline,
+ * suitable for `console.log()` or `process.stdout.write()`.
+ *
+ * @param {HelpSpec} spec
+ * @returns {string}
+ */
+export function renderHelp(spec) {
+  const lines = [];
+
+  // Title line: "Vibecarbon Backup - Create or manage backups"
+  const title = `${c.bold('Vibecarbon')} ${c.bold(capitalize(spec.name))}`;
+  if (spec.summary) {
+    lines.push(`${title} - ${spec.summary}`);
+  } else {
+    lines.push(title);
+  }
+  lines.push('');
+
+  if (spec.description) {
+    lines.push(spec.description);
+    lines.push('');
+  }
+
+  // USAGE section.
+  lines.push(c.bold('USAGE'));
+  lines.push(`  ${formatUsage(spec)}`);
+  lines.push('');
+
+  // ARGUMENTS section (only if there are positionals).
+  const positionals = spec.positional ?? [];
+  if (positionals.length > 0) {
+    lines.push(c.bold('ARGUMENTS'));
+    for (const p of positionals) {
+      const name = p.optional ? `[${p.name}]` : `<${p.name}>`;
+      const desc = p.description ?? '';
+      lines.push(`  ${c.info(name.padEnd(16))} ${c.dim(desc)}`);
+    }
+    lines.push('');
+  }
+
+  // FLAGS section.
+  const flags = spec.flags ?? [];
+  if (flags.length > 0) {
+    lines.push(c.bold('FLAGS'));
+    for (const f of flags) {
+      const display = f.value ? `-${f.name} ${f.value}` : `-${f.name}`;
+      const desc = f.description ?? '';
+      const enumNote = f.enum ? `${desc ? ' ' : ''}(${f.enum.join('|')})` : '';
+      lines.push(`  ${c.info(display.padEnd(20))} ${c.dim(desc + enumNote)}`);
+    }
+    lines.push('');
+  }
+
+  // EXAMPLES section.
+  const examples = spec.examples ?? [];
+  if (examples.length > 0) {
+    lines.push(c.bold('EXAMPLES'));
+    for (const ex of examples) {
+      if (ex.description) {
+        lines.push(`  ${c.dim(`# ${ex.description}`)}`);
+      }
+      lines.push(`  ${ex.command}`);
+      lines.push('');
+    }
+  }
+
+  return `${lines.join('\n').trimEnd()}\n`;
+}
+
+/**
+ * Build the one-line usage signature.
+ * @param {HelpSpec} spec
+ */
+function formatUsage(spec) {
+  const parts = ['vibecarbon', spec.name];
+  for (const p of spec.positional ?? []) {
+    if (p.variadic) {
+      parts.push(p.optional ? `[${p.name}...]` : `<${p.name}...>`);
+    } else {
+      parts.push(p.optional ? `[${p.name}]` : `<${p.name}>`);
+    }
+  }
+  if ((spec.flags ?? []).length > 0) {
+    parts.push('[flags]');
+  }
+  return parts.join(' ');
+}
+
+/**
+ * @param {string} s
+ * @returns {string}
+ */
+function capitalize(s) {
+  return s.length === 0 ? s : s[0].toUpperCase() + s.slice(1);
+}

package/src/lib/cli/parse-flags.js

@@ -0,0 +1,160 @@
+/**
+ * Single-dash spec-driven flag parser.
+ *
+ * Vibecarbon's CLI uses single-dash flags only (`-h`, `-env prod`,
+ * `-mode k8s`). Double-dash long flags (`--help`) are rejected — see
+ * memory:feedback_cli_single_dash_flags. Each command exports a spec
+ * declaring its flags + positionals; this parser walks argv against
+ * that spec and returns `{ values, positional, errors }`.
+ *
+ * Why a shared parser:
+ *   - Each command file used to hand-roll a `parseArgs(args)` loop.
+ *     The result was inconsistent error handling, drift between long
+ *     and short forms, and silent acceptance of typos.
+ *   - With a shared parser driven by an explicit spec, every command
+ *     gets the same diagnostics, and help-text generation has a single
+ *     authoritative source (this spec, consumed by `cli/help.js`).
+ *
+ * @typedef {object} FlagSpec
+ * @property {string} name - canonical flag name (used as `-${name}` in argv).
+ * @property {boolean} [boolean] - true for presence-only flags (`-l`, `-y`).
+ *   Boolean and value are mutually exclusive; pick one.
+ * @property {string} [value] - placeholder shown in help (e.g. `<name>`).
+ *   When set, the parser consumes the next argv element as the value.
+ * @property {string[]} [enum] - constrain a value flag to an allowed set.
+ *   The parser emits an error if the supplied value isn't in this list.
+ * @property {string} [description] - human-readable description for help.
+ *
+ * @typedef {object} PositionalSpec
+ * @property {string} name - identifier (used as the key in the result).
+ * @property {boolean} [optional=false] - if false, missing this positional
+ *   produces an error.
+ * @property {boolean} [variadic=false] - if true, all remaining positionals
+ *   are collected into an array under this name.
+ * @property {string} [description] - human-readable description for help.
+ *
+ * @typedef {object} CommandSpec
+ * @property {string} name - the command (e.g. `backup`).
+ * @property {string} [summary] - one-line description for help.
+ * @property {FlagSpec[]} [flags]
+ * @property {PositionalSpec[]} [positional]
+ *
+ * @typedef {object} ParseResult
+ * @property {Record<string, string|boolean|null>} values - flag values
+ *   keyed by canonical name. Boolean flags default to false; value flags
+ *   default to null.
+ * @property {Record<string, string|string[]|undefined>} positional -
+ *   positional values keyed by their declared name. Variadic positionals
+ *   produce an array.
+ * @property {string[]} errors - human-readable diagnostics. Empty when
+ *   parsing succeeded; the caller decides whether to print and exit.
+ */
+
+/**
+ * @param {string[]} argv - process.argv slice (without node + script).
+ * @param {CommandSpec} spec
+ * @returns {ParseResult}
+ */
+export function parseFlags(argv, spec) {
+  /** @type {Record<string, string|boolean|null>} */
+  const values = {};
+  /** @type {Record<string, string|string[]|undefined>} */
+  const positional = {};
+  /** @type {string[]} */
+  const errors = [];
+
+  const flagSpecs = spec.flags ?? [];
+  const positionalSpecs = spec.positional ?? [];
+
+  for (const f of flagSpecs) {
+    if (f.boolean && f.value !== undefined) {
+      throw new Error(`flag spec "${f.name}" has both \`boolean\` and \`value\`; pick one`);
+    }
+    values[f.name] = f.boolean ? false : null;
+  }
+
+  /** @type {string[]} */
+  const collectedPositionals = [];
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+
+    if (!arg.startsWith('-')) {
+      collectedPositionals.push(arg);
+      continue;
+    }
+
+    // Reject the empty `-` (probably a typo) and double-dash forms
+    // (`--help`, `--env=prod`). Both fall into the "unknown flag" path
+    // — vibecarbon is pre-release and intentionally has no migration
+    // shim for the dropped POSIX-long convention.
+    if (arg === '-' || arg.startsWith('--')) {
+      errors.push(`unknown flag: ${arg}`);
+      continue;
+    }
+
+    const name = arg.slice(1);
+    const flagSpec = flagSpecs.find((f) => f.name === name);
+
+    if (!flagSpec) {
+      errors.push(`unknown flag: ${arg}`);
+      continue;
+    }
+
+    if (flagSpec.boolean) {
+      values[name] = true;
+      continue;
+    }
+
+    // Value flag — consume the next argv element. Reject if the next
+    // element is missing or itself a flag (the latter usually means the
+    // operator forgot the value: `vibecarbon backup -env -y` is almost
+    // certainly a mistake, not "use literal `-y` as the env name").
+    const next = argv[i + 1];
+    if (next === undefined || next.startsWith('-')) {
+      errors.push(`flag -${name} requires a value`);
+      continue;
+    }
+    if (flagSpec.enum && !flagSpec.enum.includes(next)) {
+      errors.push(`-${name} must be one of: ${flagSpec.enum.join(', ')} (got: ${next})`);
+      // Still consume next so we don't double-report it as a stray positional.
+      i++;
+      continue;
+    }
+    values[name] = next;
+    i++;
+  }
+
+  // Distribute collected positionals across positional specs in order.
+  // A variadic spec consumes all remaining positionals, so it must be
+  // the last entry; we guard against mid-list variadics in the schema.
+  let cursor = 0;
+  for (let p = 0; p < positionalSpecs.length; p++) {
+    const ps = positionalSpecs[p];
+    if (ps.variadic) {
+      if (p !== positionalSpecs.length - 1) {
+        throw new Error(`positional "${ps.name}" is variadic but not the last entry in spec`);
+      }
+      positional[ps.name] = collectedPositionals.slice(cursor);
+      cursor = collectedPositionals.length;
+      break;
+    }
+    if (cursor < collectedPositionals.length) {
+      positional[ps.name] = collectedPositionals[cursor];
+      cursor++;
+    } else {
+      positional[ps.name] = undefined;
+      if (!ps.optional) {
+        errors.push(`missing required argument: ${ps.name}`);
+      }
+    }
+  }
+
+  // Excess positionals (operator passed more than the spec declares).
+  if (cursor < collectedPositionals.length) {
+    const extra = collectedPositionals.slice(cursor);
+    errors.push(`unexpected argument${extra.length === 1 ? '' : 's'}: ${extra.join(' ')}`);
+  }
+
+  return { values, positional, errors };
+}

package/src/lib/cli/select-action.js

@@ -0,0 +1,65 @@
+/**
+ * Action-picker prompt for commands that branch on a verb.
+ *
+ * Some commands have multiple modes — `backup` can create, list, or
+ * download; `restore` can restore from S3 or from a local file. Under
+ * the new interactive-default model, these don't surface as flags;
+ * the bare command opens an action menu after the env is selected.
+ *
+ * The seed parameter (from `-action <verb>`) lets power users skip
+ * the prompt for repeatable invocations. Validation against the
+ * options list catches typos loudly instead of silently dropping
+ * into the prompt.
+ */
+
+import * as p from '@clack/prompts';
+
+/**
+ * @typedef {object} ActionOption
+ * @property {string} value - canonical identifier; what the seed
+ *   matches against and what this helper returns.
+ * @property {string} label - what the operator sees in the picker.
+ * @property {string} [hint] - secondary text in the picker.
+ *
+ * @param {object} options
+ * @param {string} options.message - prompt text (e.g. "What do you
+ *   want to do?").
+ * @param {ActionOption[]} options.choices
+ * @param {string|null} [options.seed] - operator-supplied verb (from
+ *   the `-action` flag). When set, validated against choices and
+ *   returned directly. When null/undefined, prompt.
+ * @returns {Promise<string>} the chosen `value`.
+ */
+export async function selectAction(options) {
+  const { message, choices, seed } = options;
+
+  if (choices.length === 0) {
+    throw new Error('selectAction called with no choices — programming error');
+  }
+
+  if (seed) {
+    const known = choices.find((c) => c.value === seed);
+    if (!known) {
+      const valid = choices.map((c) => c.value).join(', ');
+      p.log.error(`Action '${seed}' is not valid. Choose one of: ${valid}.`);
+      process.exit(1);
+    }
+    return known.value;
+  }
+
+  if (choices.length === 1) {
+    return choices[0].value;
+  }
+
+  const choice = await p.select({
+    message,
+    options: choices,
+  });
+
+  if (p.isCancel(choice)) {
+    p.cancel('Operation cancelled.');
+    process.exit(0);
+  }
+
+  return /** @type {string} */ (choice);
+}

package/src/lib/cli/select-environment.js

@@ -0,0 +1,108 @@
+/**
+ * Environment-picker prompt for env-scoped commands.
+ *
+ * Replaces the older `lib/environment.js#resolveEnvironment` with a
+ * verb-aware variant suited to the new interactive-default CLI:
+ *   - The prompt + empty-state error speak in terms of the operation
+ *     ("back up", "deploy to", "destroy") so the message reads as
+ *     guidance, not a generic env picker.
+ *   - The picker hint includes the deploy status, server IP, and
+ *     primary region so multi-env operators can pick by metadata
+ *     instead of memorized name.
+ *   - The seed (positional or flag) is passed in explicitly rather
+ *     than read from a parsed-args struct, so callers using either
+ *     the new `parse-flags.js` or hand-rolled argv can both consume
+ *     it without an adapter.
+ *
+ * Returns `{ envName, envConfig }`. On empty state, missing seed
+ * with no TTY, cancel, or invalid seed, exits the process with a
+ * canonical message — same model the rest of the CLI uses for
+ * unrecoverable conditions.
+ *
+ * The old `resolveEnvironment` is retained so PR 1 doesn't change
+ * any command behavior. PR 2 migrates backup/restore to this helper
+ * and PR 6 deletes the old one.
+ */
+
+import * as p from '@clack/prompts';
+import { c } from '../colors.js';
+
+/**
+ * @param {object} projectConfig - parsed `.vibecarbon.json`.
+ * @param {object} options
+ * @param {string} options.actionVerb - imperative phrase describing
+ *   the operation, e.g. "back up", "deploy to", "restore", "destroy".
+ *   Used in prompts and empty-state messaging.
+ * @param {string|null} [options.seed] - operator-supplied env name
+ *   (from positional or flag). When set, skip the prompt and use it
+ *   directly. When null/undefined, prompt (or use the single env if
+ *   only one exists).
+ * @returns {Promise<{ envName: string, envConfig: object }>}
+ */
+export async function selectEnvironment(projectConfig, options) {
+  const { actionVerb, seed } = options;
+  const environments = projectConfig.environments || {};
+  const envNames = Object.keys(environments);
+
+  if (envNames.length === 0) {
+    p.log.error(`No deployed environments to ${actionVerb}.`);
+    p.log.info(`Run ${c.info('vibecarbon deploy')} first.`);
+    process.exit(1);
+  }
+
+  // Seed from caller — validate against known envs, fail loudly if
+  // the operator typed a name that doesn't exist (so a typo doesn't
+  // silently fall through to a prompt that gets misinterpreted).
+  if (seed) {
+    if (!environments[seed]) {
+      p.log.error(`Environment '${seed}' not found.`);
+      p.log.info(`Available: ${envNames.join(', ')}`);
+      process.exit(1);
+    }
+    return { envName: seed, envConfig: environments[seed] };
+  }
+
+  // Single-env shortcut: no point prompting when there's only one
+  // answer. The operator might still want to see which env they're
+  // operating on; surface that as a log line so the prompt isn't
+  // silently bypassed.
+  if (envNames.length === 1) {
+    const only = envNames[0];
+    p.log.info(`Using environment: ${c.bold(only)} (only deployed env)`);
+    return { envName: only, envConfig: environments[only] };
+  }
+
+  // Multi-env: render a picker with metadata-rich hints.
+  const choice = await p.select({
+    message: `Which environment to ${actionVerb}?`,
+    options: envNames.map((name) => ({
+      value: name,
+      label: name,
+      hint: formatEnvHint(environments[name]),
+    })),
+  });
+
+  if (p.isCancel(choice)) {
+    p.cancel('Operation cancelled.');
+    process.exit(0);
+  }
+
+  return { envName: /** @type {string} */ (choice), envConfig: environments[choice] };
+}
+
+/**
+ * Build the hint string shown next to each env in the picker.
+ * Combines status + region + first server IP so operators can
+ * disambiguate by deploy state at a glance.
+ *
+ * @param {object} envConfig
+ * @returns {string}
+ */
+function formatEnvHint(envConfig) {
+  const parts = [];
+  if (envConfig.status) parts.push(envConfig.status);
+  if (envConfig.region) parts.push(envConfig.region);
+  const ip = envConfig.servers?.[0]?.ip;
+  if (ip) parts.push(ip);
+  return parts.join(' · ');
+}

package/src/lib/cli/tty-guard.js

@@ -0,0 +1,75 @@
+/**
+ * TTY-detection guard for interactive-by-default commands.
+ *
+ * Vibecarbon's CLI is interactive-first: bare commands open a clack
+ * prompt flow. That model breaks when stdin isn't a TTY (CI, piped
+ * input, `< /dev/null` smoke tests). Rather than letting clack hang or
+ * silently misbehave, every command that intends to prompt calls
+ * `requireTTYOrFlags()` after parsing argv. If we're on a TTY, the call
+ * is a no-op. Off a TTY, the guard checks whether the operator supplied
+ * enough flags to skip every prompt the command would otherwise issue;
+ * if they did, fine — proceed. If they didn't, exit 1 with a message
+ * naming exactly which flags would unblock this invocation.
+ *
+ * Why this shape (and not "always require flags off-TTY"): some
+ * commands are no-prompt by nature (e.g. `vibecarbon backup -env prod
+ * -l` is a pure read). Demanding flags from those operators would be
+ * theatre. The guard takes a `requirements` array describing which
+ * prompts would otherwise run, and only complains about the ones the
+ * operator hasn't already short-circuited.
+ *
+ * @typedef {object} PromptRequirement
+ * @property {string} flag - the flag name that pre-fills this prompt
+ *   (e.g. "env", "action").
+ * @property {string} description - what this prompt would ask, in
+ *   imperative form (e.g. "select an environment").
+ * @property {boolean} satisfied - true if argv already supplies a
+ *   value (operator pre-filled via flag or positional). When false,
+ *   the command would have opened a prompt.
+ */
+
+import { c } from '../colors.js';
+
+/**
+ * Verify we're either on an interactive TTY OR the operator supplied
+ * every flag needed to skip the prompts. Exits 1 with a canonical
+ * "needs TTY or these flags" message otherwise. Returns void on
+ * success.
+ *
+ * @param {object} options
+ * @param {PromptRequirement[]} options.requirements - prompts the
+ *   command would issue without flag short-circuits.
+ * @param {NodeJS.ReadStream} [options.stdin=process.stdin] - injectable
+ *   for testing.
+ * @param {NodeJS.WriteStream} [options.stderr=process.stderr] -
+ *   injectable for testing.
+ * @param {(code: number) => never} [options.exit=process.exit] -
+ *   injectable for testing.
+ */
+export function requireTTYOrFlags(options) {
+  const {
+    requirements,
+    stdin = process.stdin,
+    stderr = process.stderr,
+    exit = /** @type {(code: number) => never} */ (process.exit.bind(process)),
+  } = options;
+
+  if (stdin.isTTY) return;
+
+  const missing = requirements.filter((r) => !r.satisfied);
+  if (missing.length === 0) return;
+
+  // Format: one line per missing prompt with the flag that would
+  // unblock it, so the operator can copy-paste a working invocation.
+  const lines = [
+    '',
+    `${c.error('✗')} This command needs an interactive terminal, or these flags to skip prompts:`,
+    '',
+    ...missing.map((m) => `    -${m.flag.padEnd(10)}  ${m.description}`),
+    '',
+    'Run again with -h for the full flag reference.',
+    '',
+  ];
+  stderr.write(`${lines.join('\n')}\n`);
+  exit(1);
+}