@terminus-ai/cli 0.0.1

package/bin/client.mjs

@@ -0,0 +1,189 @@
+/**
+ * The helpers every CLI command module shares: strict flag parsing, usage
+ * errors, the one output door (`emitJson`), the web pages the CLI points at,
+ * and writing the saved login.
+ *
+ * Talking to Terminus is bin/http.mjs's (the API base, the token, every
+ * request); errors are bin/errors.mjs's, and this module re-exports the two
+ * that command modules import from here. It knows nothing about command
+ * dispatch, terminal prompts, artifact packaging, or dev harnesses, so the
+ * executable entry point and its lazy command modules never import each
+ * other.
+ */
+
+import { chmod, mkdir, rename, rm, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+
+import {
+  COMMAND_FLAGS,
+  COMMON_FLAGS,
+  closest,
+  commandNamed,
+  missingArgumentReason,
+  renderHelp,
+  subcommandNamed,
+} from "./commands.mjs";
+import { usageError } from "./errors.mjs";
+import { normalizeBase, sessionPath } from "./http.mjs";
+
+export { CliError, usageError } from "./errors.mjs";
+
+/** Bad arguments for a known command, the way brew answers them: the
+ * command's whole help, then `Error: Invalid usage: …` naming what was wrong.
+ * `--json` carries only that last line. */
+export function commandUsageError(name, { sub, reason } = {}) {
+  const command = commandNamed(name);
+  const entry = sub ? subcommandNamed(command, sub) : command;
+  const error = usageError(`Invalid usage: ${reason ?? missingArgumentReason(entry)}`);
+  error.help = renderHelp(sub ? [name, sub] : [name]);
+  return error;
+}
+
+/** Print `value` as JSON when `--json` was passed, otherwise run the human
+ * printer. The one door every command's output goes through. */
+export function emitJson(flags, value, human) {
+  if (flags.json) {
+    console.log(JSON.stringify(value, null, 2));
+  } else if (human) {
+    human();
+  }
+}
+
+/** Strict flag parser: `--key`, `--key=value`, `--key value`; every option
+ * must be declared (by command name — see bin/commands.mjs — or an explicit
+ * spec) or parsing fails with a usage error. Keys come back snake_cased
+ * (`--use-first` → use_first). */
+export function parseFlags(args, spec = {}) {
+  const declared = typeof spec === "string" ? COMMAND_FLAGS[spec] : spec;
+  if (!declared) throw new Error(`no flag spec for command '${spec}'`);
+  const booleans = new Set([...COMMON_FLAGS.booleans, ...(declared.booleans ?? [])]);
+  const strings = new Set([...COMMON_FLAGS.strings, ...(declared.strings ?? [])]);
+  const values = { _: [] };
+  // A command's own flag mistakes come back with its help, like brew's.
+  const [specName, specSub] = typeof spec === "string" ? spec.split(" ") : [];
+  const invalid = (message) => (specName && commandNamed(specName)
+    ? commandUsageError(specName, { sub: specSub, reason: message })
+    : usageError(message));
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (!arg.startsWith("--")) {
+      values._.push(arg);
+      continue;
+    }
+    const [rawKey, inlineValue] = arg.slice(2).split("=", 2);
+    const key = rawKey.replaceAll("-", "_");
+    if (booleans.has(rawKey)) {
+      if (inlineValue !== undefined) throw invalid(`--${rawKey} does not take a value.`);
+      values[key] = true;
+      continue;
+    }
+    if (!strings.has(rawKey)) {
+      const known = [...(declared.booleans ?? []), ...(declared.strings ?? [])];
+      const suggestion = closest(rawKey, known);
+      throw invalid(`unknown option --${rawKey}${suggestion ? `; did you mean --${suggestion}?` : "."}`);
+    }
+    const value = inlineValue ?? args[++index];
+    if (value == null || value.startsWith("--")) {
+      throw invalid(`--${rawKey} requires a value.`);
+    }
+    values[key] = value;
+  }
+  return values;
+}
+
+const DEFAULT_TERMINUS_WEB_BASE = "https://www.terminus.build";
+
+/** The web portal: where creations are made, forked, and published. The CLI
+ * only moves files between a folder and a creation that already exists. */
+export function webBase(flags = {}) {
+  return normalizeBase(flags.web_base ?? process.env.TERMINUS_WEB_BASE ?? DEFAULT_TERMINUS_WEB_BASE);
+}
+
+/** The web page that makes a new creation (and shows its address). */
+export function newCreationUrl(flags = {}) {
+  return `${webBase(flags)}/os?open=create`;
+}
+
+/** One creation's page on the web, where it is published. Apps, agents, and
+ * services are keyed by their app id, skills by their uid. */
+export function creationPageUrl(flags, id) {
+  return `${webBase(flags)}/os?open=creation:${encodeURIComponent(id)}`;
+}
+
+/** A catalog artifact's public page — `/apps/@maker/notes` without the `@`,
+ * the way the web links every kind; the official tier is one segment. */
+export function artifactPageUrl(flags, artifact) {
+  const kind = artifact.kind ?? "skill";
+  const [handle, slug] = String(artifact.address ?? "").replace(/^@/, "").split("/");
+  const route = artifact.is_official
+    ? `/${kind}s/${encodeURIComponent(slug ?? handle)}`
+    : `/${kind}s/${encodeURIComponent(handle)}/${encodeURIComponent(slug ?? "")}`;
+  return `${webBase(flags)}${route}`;
+}
+
+/** What to do with a folder that is not connected to a creation yet. */
+export function notConnectedHint(flags = {}) {
+  return `create it on the web (${newCreationUrl(flags)}), then run \`terminus remote add <address>\` here`;
+}
+
+export async function writePrivateJson(file, value) {
+  const directory = path.dirname(file);
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  try {
+    await chmod(directory, 0o700);
+  } catch {
+    // Best effort on platforms/filesystems that do not support POSIX modes.
+  }
+  const temporary = path.join(directory, `.${path.basename(file)}.${randomUUID()}.tmp`);
+  try {
+    await writeFile(temporary, JSON.stringify(value, null, 2), {
+      flag: "wx",
+      mode: 0o600,
+    });
+    try {
+      await chmod(temporary, 0o600);
+    } catch {
+      // Best effort on platforms/filesystems that do not support POSIX modes.
+    }
+    // Same-directory rename keeps readers from observing a partially written
+    // bearer token and avoids following a pre-existing session-file symlink.
+    await rename(temporary, file);
+  } finally {
+    await rm(temporary, { force: true });
+  }
+}
+
+export async function saveSession(session) {
+  await writePrivateJson(sessionPath(), {
+    version: 2,
+    ...session,
+    saved_at: new Date().toISOString(),
+  });
+}
+
+export function sessionRecordFromBrowserLogin(base, login, previous = {}) {
+  const profile = login.profile ?? {};
+  const user = login.user ?? {};
+  const avatarUrl = Object.hasOwn(profile, "avatar_url")
+    ? profile.avatar_url
+    : Object.hasOwn(user, "avatar_url")
+      ? user.avatar_url
+      : previous.avatar_url;
+  return {
+    version: 3,
+    api_base: base,
+    auth_method: "browser",
+    token: login.token,
+    expires_at: login.expires_at,
+    user_id: profile.id ?? user.id ?? previous.user_id,
+    email: profile.email ?? user.email ?? login.email ?? previous.email,
+    display_name: profile.display_name ?? login.display_name ?? previous.display_name,
+    username: profile.username ?? login.username ?? user.username ?? previous.username,
+    publisher_handle: profile.publisher_handle ?? previous.publisher_handle,
+    avatar_url: avatarUrl,
+    device_name: login.device_name ?? previous.device_name,
+    platform: login.platform ?? previous.platform,
+    client_version: login.client_version ?? previous.client_version,
+  };
+}