ninedeploy 0.10.6 → 0.16.0

package/src/commands/sso.ts

@@ -0,0 +1,106 @@
+/**
+ * `ninedeploy sso {list,add,remove}` — Sprint 5, Gap G-22.
+ *
+ * Operator-side wrapper for the SSO provider list. The CLI is the
+ * canonical write path; the panel is the read + login surface.
+ */
+import type { NineDeployClient } from '../client.js';
+import { error, header, info, success } from '../lib/format.js';
+
+export interface SsoProviderListItem {
+  id: number;
+  type: 'oidc' | 'saml';
+  name: string;
+  createdAt: string;
+}
+
+// ── `ninedeploy sso list` ─────────────────────────────────────────────────
+
+/** Pure entry point — same shape used by the CLI action and the unit test. */
+export async function ssoList(client: NineDeployClient): Promise<{ providers: SsoProviderListItem[] }> {
+  return await client.sso.listProviders();
+}
+
+export async function ssoListAction(client: NineDeployClient): Promise<void> {
+  header('SSO providers');
+  let result: { providers: SsoProviderListItem[] };
+  try {
+    result = await ssoList(client);
+  } catch (err) {
+    error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+    return;
+  }
+  if (result.providers.length === 0) {
+    info('No SSO providers configured. Run `ninedeploy sso add oidc --name <id> --issuer <url> --client-id <id> --client-secret <secret>`.');
+    return;
+  }
+  for (const p of result.providers) {
+    info(`#${p.id}  ${p.name}  (${p.type})`);
+  }
+}
+
+// ── `ninedeploy sso add` ──────────────────────────────────────────────────
+
+/** Pure entry point — same shape used by the CLI action and the unit test. */
+export async function ssoAdd(
+  client: NineDeployClient,
+  type: 'oidc' | 'saml',
+  name: string,
+  config: Record<string, unknown>,
+): Promise<{ ok: boolean; id?: number; error?: string }> {
+  return await client.sso.addProvider({ type, name, config });
+}
+
+export async function ssoAddAction(
+  client: NineDeployClient,
+  type: string,
+  name: string,
+  config: Record<string, unknown>,
+): Promise<void> {
+  if (type !== 'oidc' && type !== 'saml') {
+    error('Usage: ninedeploy sso add <oidc|saml> <name> --config-key value --config-key value ...');
+    process.exitCode = 1;
+    return;
+  }
+  let result: Awaited<ReturnType<typeof ssoAdd>>;
+  try {
+    result = await ssoAdd(client, type, name, config);
+  } catch (err) {
+    error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+    return;
+  }
+  if (!result.ok) {
+    error(result.error ?? 'unknown error');
+    process.exitCode = 1;
+    return;
+  }
+  success(`Added SSO provider "${name}" (id=${result.id})`);
+}
+
+// ── `ninedeploy sso remove` ───────────────────────────────────────────────
+
+/** Pure entry point — same shape used by the CLI action and the unit test. */
+export async function ssoRemove(client: NineDeployClient, id: number): Promise<{ ok: boolean }> {
+  return await client.sso.removeProvider(id);
+}
+
+export async function ssoRemoveAction(client: NineDeployClient, idStr: string): Promise<void> {
+  const id = Number(idStr);
+  if (!Number.isFinite(id)) {
+    error('Usage: ninedeploy sso remove <id>');
+    process.exitCode = 1;
+    return;
+  }
+  let result: Awaited<ReturnType<typeof ssoRemove>>;
+  try {
+    result = await ssoRemove(client, id);
+  } catch (err) {
+    error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+    return;
+  }
+  success(`Removed SSO provider #${id}`);
+  void result;
+}

package/src/commands/templates.ts

@@ -0,0 +1,158 @@
+/**
+ * `ninedeploy templates {init}` — Sprint 1, Gap G-04, PR #4.
+ *
+ * `init <template-id>` asks the panel for one template, runs the shared
+ * `buildManifestFromTemplate` mapper (the same pure helper the server's
+ * `manifest-generator` plugin uses), and either prints the YAML to stdout
+ * or writes it to a `.ninedeploy` file in the current directory.
+ *
+ * The split is deliberate:
+ *   - Pulling the template from the panel guarantees the operator sees the
+ *     same port/volume/env the deploy will see, including any panel-side
+ *     overrides (image tag pin, runtime version, etc.).
+ *   - Building the manifest on the client keeps `ninedeploy` usable
+ *     without a running panel: `ninedeploy templates init n8n` requires
+ *     only an auth token, not a live deploy.
+ *   - All mapping logic lives in `@ninedeploy/sdk` so the panel's
+ *     `manifest-generator` plugin, this CLI command, and any future
+ *     consumer share one implementation.
+ */
+import { existsSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { buildManifestFromTemplate, formatManifestYaml, type TemplateRegistryEntry } from '@ninedeploy/sdk';
+import type { NineDeployClient } from '../client.js';
+import { error, header, info, success } from '../lib/format.js';
+
+const MANIFEST_FILENAMES = ['.ninedeploy', '.ninedeploy.yml', '.ninedeploy.yaml'] as const;
+
+function existingManifest(cwd: string): string | null {
+  for (const name of MANIFEST_FILENAMES) {
+    const candidate = resolve(cwd, name);
+    if (existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+/**
+ * Pull a single template's registry entry from the panel. The response
+ * carries every field we need; anything beyond `TemplateRegistryEntry` is
+ * ignored. The cast is safe because the server's `Template` type is a
+ * superset of the SDK's `TemplateRegistryEntry` shape.
+ */
+async function fetchTemplateEntry(
+  client: NineDeployClient,
+  templateId: string,
+): Promise<TemplateRegistryEntry> {
+  // The SDK exposes typed `client.templates.get(id)` returning `Template`.
+  // We rely on the cast here so a single helper definition lives in the
+  // SDK; if the server's response shape ever drifts, this is the seam.
+  const full = await (client as unknown as {
+    templates: { get: (id: string) => Promise<TemplateRegistryEntry> };
+  }).templates.get(templateId);
+  if (!full) throw new Error(`Panel returned no template for id "${templateId}"`);
+  return {
+    id: full.id,
+    name: full.name,
+    image: full.image,
+    port: full.port,
+    volumeMount: full.volumeMount,
+    env: full.env,
+  };
+}
+
+// ── `ninedeploy templates init <id>` ─────────────────────────────────────
+
+export interface TemplatesInitOptions {
+  /** Default host to bake into the starter `routes[0].host`. */
+  host?: string;
+  /** Filename to write when `--write` is set; defaults to `.ninedeploy`. */
+  filename?: string;
+  /** When true, write to disk; when false (default), print to stdout. */
+  write?: boolean;
+}
+
+/**
+ * Pure entry point — same shape used by both the CLI action and the
+ * unit test. Given a client and a template id, return the rendered YAML.
+ * Does not touch the filesystem or stdin; the caller decides what to do
+ * with the result.
+ */
+export async function renderTemplateManifest(
+  client: NineDeployClient,
+  templateId: string,
+  opts: TemplatesInitOptions = {},
+): Promise<{ yaml: string; entry: TemplateRegistryEntry }> {
+  const entry = await fetchTemplateEntry(client, templateId);
+  const host = opts.host?.trim() ?? '';
+  const manifest = buildManifestFromTemplate(entry, host);
+  // F929: the mapper always emits a starter route, but `routes[].host` is
+  // required (a hostname, min 3 chars) while `routes` itself is optional. With
+  // no --host, drop the route instead of writing `host: ""` that `manifest
+  // validate` and the deploy-time loader reject (mirrors the server's F336).
+  if (!host) delete manifest.routes;
+  const yaml = formatManifestYaml(manifest);
+  return { yaml, entry };
+}
+
+export async function templatesInit(
+  client: NineDeployClient,
+  templateId: string,
+  cwd: string = process.cwd(),
+  opts: TemplatesInitOptions = {},
+): Promise<void> {
+  header('Templates init');
+
+  if (!templateId) {
+    error('Usage: ninedeploy templates init <template-id>');
+    process.exitCode = 1;
+    return;
+  }
+
+  if (opts.write) {
+    const existing = existingManifest(cwd);
+    if (existing) {
+      error(`A manifest already exists at ${existing}. Refusing to overwrite.`);
+      process.exitCode = 1;
+      return;
+    }
+  }
+
+  let yaml: string;
+  let entry: TemplateRegistryEntry;
+  try {
+    ({ yaml, entry } = await renderTemplateManifest(client, templateId, opts));
+  } catch (err) {
+    error(
+      err instanceof Error
+        ? `Could not fetch template "${templateId}": ${err.message}`
+        : `Could not fetch template "${templateId}"`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  if (opts.write) {
+    const filename = opts.filename ?? '.ninedeploy';
+    const out = resolve(cwd, filename);
+    writeFileSync(out, yaml, 'utf8');
+    success(`Wrote ${filename}`);
+    // v8 ignore next -- the post-write banner lines are reached only
+    // when the user runs the action via the CLI; the only test that
+    // does that is the end-to-end smoke in test/index.test.ts, which v8
+    // attributes to the call site rather than this branch.
+    info(`Image: ${entry.image}`);
+    if (entry.port) info(`Port:  ${entry.port}`);
+    if (entry.volumeMount) info(`Mount: ${entry.volumeMount}`);
+    info('Edit the file to match your project, then commit it.');
+    info('Run `ninedeploy manifest validate` to check it before pushing.');
+  } else {
+    // Print to stdout so the operator can pipe to `tee`, redirect into a
+    // file, or diff against an existing one. The header/footer banners
+    // are only useful interactively, so they go to stderr.
+    process.stdout.write(yaml);
+    if (!process.stdout.isTTY) {
+      // v8 ignore next -- see note above.
+      info(`(rendered from template "${entry.id}" — pipe to a file or diff with --write)`);
+    }
+  }
+}

package/src/commands/token.ts

@@ -0,0 +1,66 @@
+import { NineDeployError } from '@ninedeploy/sdk';
+import { getClient } from '../client.js';
+import { prompt } from '../prompts.js';
+
+/**
+ * Normalise a typed scope answer. Accepts the legacy
+ * `read | write | operator` shorthand AND the fine-grained
+ * `nd://scope/(read|write|admin)/<resource>` form
+ * introduced in G-08. Anything unrecognised is dropped
+ * rather than silently widening the token. An empty
+ * result means "no scopes given": callers omit the field
+ * and the server applies its read-only default (the
+ * server refuses an explicit `[]`, which would be stored
+ * as a legacy unrestricted token).
+ */
+export function parseScopes(answer: string): string[] {
+  const legacy = new Set(['read', 'write', 'operator']);
+  const resourceScope = /^nd:\/\/scope\/(read|write|admin)\/[a-z][a-z0-9_]{0,63}$/;
+  return answer
+    .split(',')
+    .map((s) => s.trim())
+    .filter((s) => legacy.has(s) || resourceScope.test(s));
+}
+
+/** `ninedeploy token create` — mint an API token (shown once). */
+export async function tokenCreateAction(): Promise<void> {
+  const name = (await prompt('Token name', 'ci')) || 'ci';
+  // read = safe methods only · write = mutate as a non-operator ·
+  // operator = no extra restriction. Blank = read-only (server default).
+  // r194: the default must match the label — it was 'write', so pressing
+  // Enter at "blank = read" minted a write token.
+  const scopes = parseScopes(await prompt('Scopes (read,write,operator — blank = read)', 'read'));
+  try {
+    const created = await getClient().auth.tokens.create(scopes.length ? { name, scopes } : { name });
+    console.log(`✓ Token "${created.name}" created (id: ${created.id}).`);
+    console.log(`  Scopes: ${created.scopes.length ? created.scopes.join(', ') : 'unrestricted (legacy)'}`);
+    console.log('  This token is shown ONCE — store it securely:');
+    console.log(`  ${created.token}`);
+    console.log('  Use it as: Authorization: Bearer <token>');
+  } catch (err) {
+    console.error(
+      '✗ Could not create token:',
+      err instanceof NineDeployError ? err.message : err instanceof Error ? err.message : err,
+    );
+    process.exitCode = 1;
+  }
+}
+
+/** `ninedeploy token list` — list API tokens (without secrets). */
+export async function tokenListAction(): Promise<void> {
+  const tokens = await getClient().auth.tokens.list();
+  if (tokens.length === 0) {
+    console.log('No API tokens.');
+    return;
+  }
+  console.table(
+    tokens.map((t) => ({
+      id: t.id,
+      name: t.name,
+      scopes: t.scopes.length ? t.scopes.join(',') : 'unrestricted',
+      lastUsed: t.lastUsedAt ?? 'never',
+      expires: t.expiresAt ?? 'never',
+      created: t.createdAt,
+    })),
+  );
+}

package/src/commands/webhooks.ts

@@ -0,0 +1,93 @@
+import type { NineDeployClient } from '../client.js';
+import { prompt } from '../prompts.js';
+import { c, error, header, info, kv, spinner, success, table } from '../lib/format.js';
+
+/** `ninedeploy webhooks list <serviceId>` */
+export async function webhooksList(client: NineDeployClient, svcArg: string): Promise<void> {
+  const serviceId = Number(svcArg);
+  if (!serviceId) return error('Usage: ninedeploy webhooks list <serviceId>');
+  header(`Webhooks for service #${serviceId}`);
+  const rows = await spinner('Fetching', () => client.webhooks.list(serviceId));
+  if (rows.length === 0) {
+    info('No webhooks yet. Add one with `ninedeploy webhooks add`.');
+    return;
+  }
+  table(
+    rows.map((w) => ({
+      id: w.id,
+      branch: w.branch,
+      source: w.sourceId ?? c.gray('—'),
+      active: w.active ? c.green('✓') : c.red('✗'),
+      url: w.url,
+    })),
+    ['id', 'branch', 'source', 'active', 'url'],
+  );
+}
+
+/**
+ * `ninedeploy webhooks add <serviceId> [branch]`
+ *
+ * Returns the secret ONCE so the operator can paste it into GitHub as the
+ * webhook "Secret" value. The CLI never stores it; the panel only ever sees
+ * the HMAC digest.
+ */
+export async function webhooksAdd(client: NineDeployClient, svcArg: string, branchArg?: string): Promise<void> {
+  const serviceId = Number(svcArg);
+  if (!serviceId) return error('Usage: ninedeploy webhooks add <serviceId> [branch]');
+  const branch = branchArg ?? (await prompt('Branch to deploy on push', 'main'));
+  if (!branch) return error('Branch is required');
+
+  const watchPaths = (await prompt('Watch paths (newline/comma-separated globs; empty = all files)', '')) || undefined;
+
+  const created = await spinner('Creating webhook', () =>
+    client.webhooks.create(serviceId, { branch, watchPaths }),
+  );
+  success(`Webhook #${created.id} created for branch "${created.branch}"`);
+  console.log();
+  console.log(`  ${c.bold('URL')}`);
+  console.log(`    ${c.cyan(created.url)}`);
+  console.log();
+  console.log(`  ${c.bold('Secret (shown once — paste into GitHub):')}`);
+  console.log(`    ${c.green(created.secret)}`);
+  console.log();
+  console.log(`  ${c.gray('GitHub steps: Repo → Settings → Webhooks → Add')}`);
+  console.log(`  ${c.gray('  • Payload URL  : the URL above')}`);
+  console.log(`  ${c.gray('  • Content type : application/json')}`);
+  console.log(`  ${c.gray('  • Secret       : the secret above')}`);
+  console.log(`  ${c.gray('  • SSL          : enabled (the panel runs behind HTTPS via Traefik)')}`);
+  console.log(`  ${c.gray('  • Events       : "Just the push event."')}`);
+  console.log();
+  info('Tip: set `NINEDEPLOY_PUBLIC_URL` on the server to a public HTTPS URL so the URL is reachable from GitHub.');
+}
+
+/** `ninedeploy webhooks remove <serviceId> <hookId>` */
+export async function webhooksRemove(client: NineDeployClient, svcArg: string, hookArg: string): Promise<void> {
+  const serviceId = Number(svcArg);
+  const hookId = Number(hookArg);
+  if (!serviceId || !hookId) return error('Usage: ninedeploy webhooks remove <serviceId> <hookId>');
+  const confirm = await prompt(`Type "delete" to confirm removal of webhook #${hookId}`, '');
+  if (confirm.trim() !== 'delete') {
+    info('Aborted.');
+    return;
+  }
+  await spinner('Removing webhook', () => client.webhooks.remove(serviceId, hookId));
+  success(`Webhook #${hookId} removed.`);
+}
+
+/** `ninedeploy webhooks show <serviceId> <hookId>` */
+export async function webhooksShow(client: NineDeployClient, svcArg: string, hookArg: string): Promise<void> {
+  const serviceId = Number(svcArg);
+  const hookId = Number(hookArg);
+  if (!serviceId || !hookId) return error('Usage: ninedeploy webhooks show <serviceId> <hookId>');
+  header(`Webhook #${hookId}`);
+  const rows = await spinner('Fetching', () => client.webhooks.list(serviceId));
+  const w = rows.find((x) => x.id === hookId);
+  if (!w) return error(`Webhook #${hookId} not found on service #${serviceId}`);
+  kv('ID', w.id);
+  kv('Branch', w.branch);
+  kv('Source', w.sourceId ?? c.gray('— (inherits service default)'));
+  kv('Active', w.active ? c.green('yes') : c.red('no'));
+  kv('Watch paths', w.watchPaths || c.gray('— (all files)'));
+  kv('URL', w.url);
+  kv('Created', w.createdAt);
+}

package/src/commands/workspaces.ts

@@ -0,0 +1,63 @@
+import type { NineDeployClient } from '@ninedeploy/sdk';
+import { spinner, table } from '../lib/format.js';
+
+export async function workspacesList(client: NineDeployClient): Promise<void> {
+  const list = await spinner('Fetching workspaces', () => client.workspaces.list());
+  if (list.length === 0) {
+    console.log('  No workspaces found.');
+    return;
+  }
+  table(
+    list.map((w) => ({
+      id: w.id,
+      name: w.name,
+      slug: w.slug,
+      role: w.myRole,
+      members: w.memberCount,
+      projects: w.projectCount,
+      created: new Date(w.createdAt).toLocaleDateString(),
+    })),
+    ['id', 'name', 'slug', 'role', 'members', 'projects', 'created'],
+  );
+}
+
+export async function workspacesGet(client: NineDeployClient, id: string): Promise<void> {
+  const wsId = Number.parseInt(id, 10);
+  if (Number.isNaN(wsId)) {
+    throw new Error('Workspace ID must be an integer');
+  }
+  const ws = await spinner('Fetching workspace', () => client.workspaces.get(wsId));
+  console.log(`\n  Workspace #${ws.id}: ${ws.name} (${ws.slug})`);
+  console.log(`  Role:        ${ws.myRole}`);
+  if (ws.description) console.log(`  Description: ${ws.description}`);
+  console.log(`  Created:     ${new Date(ws.createdAt).toLocaleString()}`);
+  console.log('\n  Members:');
+  table(
+    ws.members.map((m) => ({
+      userId: m.userId,
+      nameEmail: m.name ? `${m.name} <${m.email}>` : m.email,
+      role: m.role,
+      joined: new Date(m.createdAt).toLocaleDateString(),
+    })),
+    ['userId', 'nameEmail', 'role', 'joined'],
+  );
+}
+
+export async function workspacesCreate(client: NineDeployClient, name: string, opts: { description?: string }): Promise<void> {
+  const ws = await spinner('Creating workspace', () =>
+    client.workspaces.create({
+      name,
+      description: opts.description,
+    }),
+  );
+  console.log(`  ✓ Workspace #${ws.id} created: ${ws.name} (${ws.slug})`);
+}
+
+export async function workspacesDelete(client: NineDeployClient, id: string): Promise<void> {
+  const wsId = Number.parseInt(id, 10);
+  if (Number.isNaN(wsId)) {
+    throw new Error('Workspace ID must be an integer');
+  }
+  await spinner('Deleting workspace', () => client.workspaces.delete(wsId));
+  console.log(`  ✓ Workspace #${wsId} deleted.`);
+}

package/src/config.ts

@@ -0,0 +1,53 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { randomUUID } from 'node:crypto';
+import path from 'node:path';
+
+const CONFIG_DIR = path.join(homedir(), '.ninedeploy');
+const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
+
+export interface CliConfig {
+  baseUrl: string;
+  token?: string;
+  /** Long-lived token used to mint fresh access tokens (see client.ts). */
+  refreshToken?: string;
+}
+
+const DEFAULTS: CliConfig = { baseUrl: 'http://localhost:3000' };
+
+export function loadConfig(): CliConfig {
+  try {
+    if (existsSync(CONFIG_FILE)) {
+      return { ...DEFAULTS, ...(JSON.parse(readFileSync(CONFIG_FILE, 'utf8')) as Partial<CliConfig>) };
+    }
+  } catch (err) {
+    // A torn/partial write used to fall back to defaults SILENTLY — the user
+    // was logged out with no hint the file was ever corrupt. Say so.
+    // eslint-disable-next-line no-console
+    console.error(`⚠ Could not read ${CONFIG_FILE} (${err instanceof Error ? err.message : String(err)}); using defaults.`);
+  }
+  return { ...DEFAULTS };
+}
+
+export function saveConfig(config: CliConfig): void {
+  mkdirSync(CONFIG_DIR, { recursive: true });
+  // Temp-file + rename: a crash mid-write must never leave a half-written
+  // config behind (the previous direct write could, logging the user out on
+  // the next command with no explanation).
+  const tmp = `${CONFIG_FILE}.${randomUUID()}.tmp`;
+  writeFileSync(tmp, JSON.stringify(config, null, 2), { mode: 0o600 });
+  try {
+    renameSync(tmp, CONFIG_FILE);
+  } catch (err) {
+    try { unlinkSync(tmp); } catch { /* already gone */ }
+    throw err;
+  }
+  // writeFileSync's mode only applies at CREATION — re-assert 0600 so a file
+  // that ever ended up group/world-readable (restore, copy, old version)
+  // holding the bearer token is tightened on every save.
+  try {
+    chmodSync(CONFIG_FILE, 0o600);
+  } catch {
+    /* best-effort on exotic filesystems */
+  }
+}