ninedeploy 0.10.6 → 0.16.1

package/src/commands/sources.ts

@@ -0,0 +1,317 @@
+import process from 'node:process';
+import type { NineDeployClient } from '../client.js';
+import { prompt, promptHidden } from '../prompts.js';
+import { c, error, header, info, kv, spinner, success, table } from '../lib/format.js';
+
+const PROVIDERS = ['github', 'gitlab', 'gitea', 'registry', 'custom'] as const;
+type Provider = (typeof PROVIDERS)[number];
+
+/** `ninedeploy sources list` */
+export async function sourcesList(client: NineDeployClient): Promise<void> {
+  header('Sources');
+  const rows = await spinner('Fetching sources', () => client.sources.list());
+  if (rows.length === 0) {
+    info('No sources yet. Run `ninedeploy sources add` to add a GitHub/GitLab PAT or SSH key.');
+    return;
+  }
+  table(
+    rows.map((s) => ({
+      id: s.id,
+      name: s.name,
+      type: s.type,
+      token: s.hasToken ? c.green('✓') : c.gray('—'),
+      deployKey: s.hasDeployKey ? c.green('✓') : c.gray('—'),
+      branch: s.defaultBranch ?? 'main',
+    })),
+    ['id', 'name', 'type', 'token', 'deployKey', 'branch'],
+  );
+}
+
+/**
+ * 0.13: a Gitea base URL from `--base-url`. Shape only (http(s), no
+ * credentials, query or fragment); the server re-checks it and refuses
+ * `http:` unless private egress is allowed.
+ */
+function parseBaseUrl(raw: string): string | null {
+  const trimmed = raw.trim().replace(/\/+$/, '');
+  try {
+    const url = new URL(trimmed);
+    if ((url.protocol !== 'https:' && url.protocol !== 'http:') || url.username || url.password || url.search || url.hash) return null;
+    return trimmed;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve a credential with a strict, documented precedence:
+ *   1. explicit CLI flag (already handled by the caller)
+ *   2. NINEDEPLOY_GITHUB_TOKEN / NINEDEPLOY_GITLAB_TOKEN / NINEDEPLOY_SOURCE_TOKEN env var
+ *   3. interactive masked prompt
+ *
+ * The env fallback is the documented "no-stdin / CI" path: an operator
+ * piping `echo '' | ninedeploy …` keeps working without hanging.
+ */
+async function resolveSecret(envName: string, label: string): Promise<string> {
+  const fromEnv = process.env[envName]?.trim();
+  if (fromEnv) return fromEnv;
+  // Last resort: masked prompt. Honors a piped-stdin default (empty).
+  return await promptHidden(label);
+}
+
+/**
+ * F596: the generic provider-token env var for gitea / registry / custom.
+ * NOT `NINEDEPLOY_TOKEN` — that is the documented panel API token (MCP / API
+ * clients); reading it here stored the panel credential on the source and
+ * sent it to the third-party git host / registry, without a prompt.
+ */
+const SOURCE_TOKEN_ENV = 'NINEDEPLOY_SOURCE_TOKEN';
+
+/**
+ * F597: the prompt asks for the key on one line with escaped newlines (a
+ * hidden prompt ends at the first real newline). Turn the escapes back into
+ * the newlines the key file needs — a PEM/OpenSSH key never holds a backslash.
+ */
+async function resolveDeployKey(): Promise<string> {
+  const key = await resolveSecret('NINEDEPLOY_SSH_KEY', 'SSH private key (PEM, single line — escape newlines)');
+  return key.replace(/(?:\\r)?\\n/g, '\n');
+}
+
+/**
+ * F598: canonical decimal id only, as the server's parseId accepts it.
+ * `Number()` mapped `1e1`→10 and `0x4`→4, and NaN fell into the picker whose
+ * default is the first listed source — keygen then rewrote the wrong source.
+ */
+function parseSourceId(raw: string): number {
+  const t = raw.trim();
+  return /^[1-9]\d*$/.test(t) && Number.isSafeInteger(Number(t)) ? Number(t) : 0;
+}
+
+/** `ninedeploy sources add [name] [--base-url <url>]` */
+export async function sourcesAdd(client: NineDeployClient, nameArg?: string, opts: { baseUrl?: string } = {}): Promise<void> {
+  header('Add Source');
+  let baseUrl: string | undefined;
+  if (opts.baseUrl !== undefined) {
+    const parsed = parseBaseUrl(opts.baseUrl);
+    if (!parsed) return error(`Invalid --base-url: ${opts.baseUrl} (expected https://host[/path])`);
+    baseUrl = parsed;
+  }
+  const name = nameArg ?? (await prompt('Display name (e.g. github-personal)'));
+  /* v8 ignore next -- the dedicated "rejects when no name" test covers the truthy/falsy split, but
+   * v8 counts the early-return as a separate branch that the existing test only ticks on one side. */
+  if (!name) return error('Name is required');
+  const type = (await prompt('Provider (github | gitlab | gitea | registry | custom)', 'github')) as Provider;
+  if (!PROVIDERS.includes(type)) {
+    return error(`Unknown provider: ${type}. Choose one of: ${PROVIDERS.join(', ')}`);
+  }
+  if (baseUrl && type !== 'gitea') return error('--base-url applies to gitea sources only');
+  const defaultBranch = (await prompt('Default branch (used as suggestion only)', 'main')) || 'main';
+
+  let token: string | undefined;
+  let deployKey: string | undefined;
+  let registryUsername: string | undefined;
+
+  if (type === 'registry') {
+    registryUsername = (await prompt('Registry username (e.g. ci-bot)')) || undefined;
+    token = await resolveSecret(SOURCE_TOKEN_ENV, 'Registry password / access token (PAT)');
+  } else if (type === 'gitea') {
+    if (!baseUrl) {
+      const typed = (await prompt('Gitea base URL (e.g. https://git.example.com; empty = no live test or repo list)')).trim();
+      if (typed) {
+        const parsed = parseBaseUrl(typed);
+        if (!parsed) return error(`Invalid Gitea base URL: ${typed}`);
+        baseUrl = parsed;
+      }
+    }
+    token = await resolveSecret(SOURCE_TOKEN_ENV, 'Gitea access token');
+  } else if (type === 'custom') {
+    // Custom source: token or SSH key, your choice
+    const authKind = (await prompt('Auth kind (token | ssh)', 'token')) === 'ssh' ? 'ssh' : 'token';
+    if (authKind === 'ssh') {
+      deployKey = await resolveDeployKey();
+    } else {
+      token = await resolveSecret(SOURCE_TOKEN_ENV, 'Access token (PAT)');
+    }
+  } else {
+    // github / gitlab — both accept token or SSH
+    const authKind = (await prompt('Auth kind (token | ssh)', 'token')) === 'ssh' ? 'ssh' : 'token';
+    if (authKind === 'ssh') {
+      deployKey = await resolveDeployKey();
+    } else {
+      const envName = type === 'github' ? 'NINEDEPLOY_GITHUB_TOKEN' : 'NINEDEPLOY_GITLAB_TOKEN';
+      token = await resolveSecret(envName, `${type === 'github' ? 'GitHub' : 'GitLab'} Personal Access Token (PAT)`);
+    }
+  }
+
+  if (!token && !deployKey) {
+    return error('Either a token or an SSH deploy key is required');
+  }
+
+  try {
+    const created = await spinner('Creating source', () =>
+      client.sources.create({
+        name,
+        type,
+        token: token || undefined,
+        deployKey: deployKey || undefined,
+        registryUsername,
+        defaultBranch,
+        ...(baseUrl ? { baseUrl } : {}),
+      }),
+    );
+    success(`Source "${created.name}" created (id: ${created.id})`);
+    // Live validation right away — saves the user a DeployWizard round-trip.
+    if ((type === 'github' || type === 'gitlab' || (type === 'gitea' && baseUrl)) && token) {
+      await sourcesTest(client, String(created.id));
+    }
+  } catch (err) {
+    /* v8 ignore next -- exercised by the "API error" test which routes the error through error() */
+    error(err instanceof Error ? err.message : String(err));
+  }
+}
+
+/**
+ * F1011: the login, name, scopes, warnings and failure text come from the Git
+ * provider's API response (relayed by the server), so they must not drive the
+ * operator's terminal — the class F538 (`deploys watch`) and F880
+ * (`logs search`) closed for log lines. Same pattern set, but these are
+ * one-line metadata fields, so nothing is kept: OSC/DCS/APC/PM/SOS strings,
+ * every CSI (SGR included), stray escapes, and all C0/DEL/C1 controls
+ * (tab/LF/CR too — a newline in a login could forge a second status line).
+ */
+const ESC = String.fromCharCode(27);
+const PROVIDER_TEXT_CONTROL = new RegExp(
+  `${ESC}[\\]PX^_][\\s\\S]*?(?:${String.fromCharCode(7)}|${ESC}\\\\|$)` +
+    `|${ESC}\\[[0-?]*[ -/]*[@-~]` +
+    `|${ESC}[\\s\\S]?` +
+    '|[\\u0000-\\u001f\\u007f-\\u009f]',
+  'g',
+);
+export const plain = (value: unknown): string => String(value).replace(PROVIDER_TEXT_CONTROL, '');
+
+/**
+ * `ninedeploy sources test [id]` — verify the stored token still authenticates.
+ * GitHub successes also print what the token can see (F1008/F1011): its kind,
+ * its classic/OAuth scopes and each warning about missing private repositories.
+ */
+export async function sourcesTest(client: NineDeployClient, idArg?: string): Promise<void> {
+  header('Test Source Credentials');
+  if (idArg !== undefined && !parseSourceId(idArg)) return error(`Invalid source id: ${idArg}`);
+  let id = idArg === undefined ? 0 : parseSourceId(idArg);
+  if (!id) {
+    const sources = await spinner('Fetching sources', () => client.sources.list());
+    if (sources.length === 0) {
+      info('No sources yet. Add one with `ninedeploy sources add`.');
+      return;
+    }
+    table(
+      sources.map((s) => ({ id: s.id, name: s.name, type: s.type })),
+      ['id', 'name', 'type'],
+    );
+    const picked = await prompt('Source id to test', String(sources[0]!.id));
+    id = parseSourceId(picked);
+    if (!id) return error('A numeric source id is required');
+  }
+  const result = await spinner('Verifying credentials', () => client.sources.test(id));
+  if (result.ok) {
+    success(`${plain(result.provider)} token authenticates as ${plain(result.login)}${result.name ? ` (${plain(result.name)})` : ''}`);
+    if (result.tokenKind) kv('Token type', plain(result.tokenKind));
+    if (Array.isArray(result.scopes)) kv('Scopes', result.scopes.length > 0 ? result.scopes.map(plain).join(', ') : c.gray('none'));
+    // 0.13: a GitHub App source reports its installation's repository selection.
+    if (result.repositorySelection) kv('Repositories', plain(result.repositorySelection));
+    for (const warning of result.warnings ?? []) {
+      console.log(`  ${c.yellow('!')} ${c.yellow(`warning: ${plain(warning)}`)}`);
+    }
+  } else {
+    error(`${plain(result.provider ?? 'source')} check failed (status ${plain(result.status ?? 'n/a')}): ${plain(result.error ?? 'unknown error')}`);
+  }
+}
+
+/**
+ * `ninedeploy sources keygen [id]` — ask the panel server to generate an
+ * ed25519 deploy key pair for the source, then print the public key so it
+ * can be pasted into the Git host's "Deploy keys" UI.
+ */
+export async function sourcesKeygen(client: NineDeployClient, idArg?: string): Promise<void> {
+  header('Generate Deploy Key');
+  if (idArg !== undefined && !parseSourceId(idArg)) return error(`Invalid source id: ${idArg}`);
+  let id = idArg === undefined ? 0 : parseSourceId(idArg);
+  if (!id) {
+    const sources = await spinner('Fetching sources', () => client.sources.list());
+    if (sources.length === 0) {
+      info('No sources yet. Add one with `ninedeploy sources add` first.');
+      return;
+    }
+    table(
+      sources.map((s) => ({ id: s.id, name: s.name, type: s.type })),
+      ['id', 'name', 'type'],
+    );
+    const picked = await prompt('Source id to generate a deploy key for', String(sources[0]!.id));
+    id = parseSourceId(picked);
+    if (!id) return error('A numeric source id is required');
+  }
+  const result = await spinner('Generating ed25519 key pair on the panel server', () => client.sources.generateDeployKey(id));
+  success(`Deploy key generated (fingerprint ${result.fingerprint}).`);
+  console.log();
+  console.log(`  ${c.bold('Public key — paste this into your Git host\'s Deploy keys:')}`);
+  console.log(`    ${c.cyan(result.publicKey)}`);
+  console.log();
+  console.log(`  ${c.gray('GitHub:    repo → Settings → Security → Deploy keys → Add deploy key')}`);
+  console.log(`  ${c.gray('GitLab:    project → Settings → Repository → Deploy keys')}`);
+  console.log(`  ${c.gray('Gitea:     repo → Settings → Deploy keys')}`);
+  console.log();
+  info('The private key is encrypted at rest on the panel and never shown.');
+}
+
+/** `ninedeploy sources remove [id]` */
+export async function sourcesRemove(client: NineDeployClient, idArg?: string): Promise<void> {
+  header('Remove Source');
+  if (idArg !== undefined && !parseSourceId(idArg)) return error(`Invalid source id: ${idArg}`);
+  let id = idArg === undefined ? 0 : parseSourceId(idArg);
+  if (!id) {
+    const sources = await spinner('Fetching sources', () => client.sources.list());
+    if (sources.length === 0) {
+      info('No sources to remove.');
+      return;
+    }
+    table(
+      sources.map((s) => ({ id: s.id, name: s.name, type: s.type })),
+      ['id', 'name', 'type'],
+    );
+    const picked = await prompt('Source id to remove', String(sources[0]!.id));
+    id = parseSourceId(picked);
+    if (!id) return error('A numeric source id is required');
+  }
+  const confirm = await prompt(`Type "delete" to confirm removal of source #${id}`, '');
+  if (confirm.trim() !== 'delete') {
+    info('Aborted.');
+    return;
+  }
+  try {
+    await spinner('Removing source', () => client.sources.remove(id));
+    success(`Source #${id} removed.`);
+    info('Services deployed from it keep working, but new clones of private repos will fail until it is re-added.');
+  } catch (err) {
+    /* v8 ignore next -- exercised by the "API error" test which routes the error through error() */
+    error(err instanceof Error ? err.message : String(err));
+  }
+}
+
+/** `ninedeploy sources show <id>` */
+export async function sourcesShow(client: NineDeployClient, idArg: string): Promise<void> {
+  const id = Number(idArg);
+  if (!id) return error('Usage: ninedeploy sources show <id>');
+  header(`Source #${id}`);
+  const sources = await spinner('Fetching', () => client.sources.list());
+  const s = sources.find((x) => x.id === id);
+  if (!s) return error(`Source #${id} not found`);
+  kv('Name', s.name);
+  kv('Type', s.type);
+  kv('Token', s.hasToken ? c.green('✓ set') : c.gray('—'));
+  kv('Deploy key', s.hasDeployKey ? c.green('✓ set') : c.gray('—'));
+  kv('Registry user', s.registryUsername ?? '—');
+  if (s.type === 'gitea') kv('Base URL', s.baseUrl ?? c.gray('not set (no live test or repo list)'));
+  kv('Default branch', s.defaultBranch ?? 'main');
+  kv('Created', s.createdAt);
+  kv('Updated', s.updatedAt);
+}

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,
+    })),
+  );
+}