@canner-ca/cli 0.2.0 → 0.3.0

package/README.md

@@ -60,6 +60,33 @@ canner deploy --follow
 | `canner cancel [<id>] [--slug X]` | Abort the in-flight build (or a specific one by id). |
 | `canner logs [--slug X] [--lines N] [--follow]` | Stream the running tenant's runtime logs (last 200 lines by default). |
 
+### Resources
+
+| Command | What it does |
+|---|---|
+| `canner token list` | List your `cnr_` API tokens. |
+| `canner token create <name>` | Mint a new token. The secret is printed once — copy it immediately. |
+| `canner token revoke <id\|name>` | Revoke a token. |
+| `canner env [list] [--slug X]` | List a project's environment variables. |
+| `canner env set KEY=VALUE [--env production\|preview] [--sensitive] [--slug X]` | Add an environment variable. |
+| `canner env rm <KEY\|id> [--env ...] [--slug X]` | Delete an environment variable. |
+| `canner domains [list] [--slug X]` | List a project's custom domains. |
+| `canner domains add <hostname> [--slug X]` | Attach a custom domain (starts `pending`). |
+| `canner domains verify <hostname\|id> [--slug X]` | Re-check DNS and provision TLS. |
+| `canner domains rm <hostname\|id> [--slug X]` | Detach a custom domain. |
+
+## JSON output
+
+Add `--json` to any command for machine-readable output — tables and progress lines are suppressed and a single JSON value is printed to stdout, so the result pipes straight into `jq` or an agent. Errors are written to stderr as `{"error":"..."}` with a non-zero exit code. With `--json`, `deploy --follow` does **not** stream the build log (it would corrupt the JSON); poll `canner deployments <id> --json` for the terminal status instead.
+
+```bash
+canner projects --json | jq -r '.[].slug'
+canner deploy --json                      # → {"deployment_id":"…","status":"queued",…}
+canner env list --slug my-app --json
+```
+
+This pairs with the REST API directly: every command wraps an endpoint documented in the [API reference](https://canner.ca/developers) (interactive explorer at <https://api.canner.ca/docs>, OpenAPI spec at <https://api.canner.ca/openapi.json>).
+
 ## What gets uploaded
 
 The CLI tars the current directory into a `.tar.gz`, excludes the "build noise" defaults, and streams it to the same upload endpoint the dashboard's drag-drop uses. The server-side build pipeline detects the framework and runs install / build / deploy just like a `git push`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canner-ca/cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Canner deploy CLI — git push from any terminal, no GitHub required",
   "type": "module",
   "bin": {

package/src/cli.mjs

@@ -27,7 +27,7 @@ import { randomUUID } from 'node:crypto';
 import { stdin as input, stdout as output } from 'node:process';
 import { create as tarCreate } from 'tar';
 
-const VERSION = '0.2.0';
+const VERSION = '0.3.0';
 const DEFAULT_API_BASE = 'https://api.canner.ca';
 const CONFIG_DIR = join(homedir(), '.canner');
 const CREDENTIALS_PATH = join(CONFIG_DIR, 'credentials');
@@ -61,16 +61,33 @@ const green = c('32');
 const yellow = c('33');
 const cyan = c('36');
 
+// Machine-readable output mode (`--json`). Set once in main from argv. In JSON
+// mode every command prints a single JSON value to stdout and nothing else, so
+// the output pipes straight into `jq` or an agent; errors become
+// {"error":"..."} on stderr with a non-zero exit. Human-facing helpers
+// (info/muted) go silent so they can't corrupt the JSON stream.
+let JSON_MODE = false;
+
+function emitJSON(value) {
+  process.stdout.write(JSON.stringify(value, null, 2) + '\n');
+}
+
 function die(msg, code = 1) {
-  process.stderr.write(`${red('error:')} ${msg}\n`);
+  if (JSON_MODE) {
+    process.stderr.write(JSON.stringify({ error: String(msg) }) + '\n');
+  } else {
+    process.stderr.write(`${red('error:')} ${msg}\n`);
+  }
   process.exit(code);
 }
 
 function info(msg) {
+  if (JSON_MODE) return;
   process.stdout.write(`${msg}\n`);
 }
 
 function muted(msg) {
+  if (JSON_MODE) return;
   process.stdout.write(`${dim(msg)}\n`);
 }
 
@@ -275,19 +292,23 @@ async function cmdWhoami() {
   if (!me?.account) {
     die('authenticated but /auth/me returned no account.');
   }
-  info(`${bold(me.account.email)}`);
-  muted(`api: ${creds.apiBase}`);
   // Projects count from /me/plan (cheap call we already have).
+  let plan = null;
   try {
-    const plan = await apiJSON(creds, 'GET', '/me/plan');
-    if (plan?.plan) {
-      muted(
-        `plan: ${plan.plan.display_name} (${plan.project_count}/${plan.project_count_limit} projects)`
-      );
-    }
+    plan = await apiJSON(creds, 'GET', '/me/plan');
   } catch {
     // /me/plan is optional context; not fatal if it fails.
   }
+  if (JSON_MODE) {
+    return emitJSON({ account: me.account, api_base: creds.apiBase, plan: plan ?? null });
+  }
+  info(`${bold(me.account.email)}`);
+  muted(`api: ${creds.apiBase}`);
+  if (plan?.plan) {
+    muted(
+      `plan: ${plan.plan.display_name} (${plan.project_count}/${plan.project_count_limit} projects)`
+    );
+  }
 }
 
 async function cmdInit(args) {
@@ -372,6 +393,7 @@ async function cmdProjects() {
   if (!creds.token) die("not signed in. Run `canner login`.");
   const body = await apiJSON(creds, 'GET', '/projects');
   const rows = body?.projects ?? body ?? [];
+  if (JSON_MODE) return emitJSON(rows);
   if (!Array.isArray(rows) || rows.length === 0) {
     muted('no projects yet. Run `canner init` to create one.');
     return;
@@ -394,6 +416,7 @@ async function cmdStatus(args) {
   const body = await apiJSON(creds, 'GET', `/projects/${encodeURIComponent(slug)}`);
   const p = body?.project ?? body;
   if (!p?.slug) die('unexpected response from /projects/:slug');
+  if (JSON_MODE) return emitJSON(p);
   info(`${bold(p.slug)} ${dim(`(${p.name ?? ''})`)}`);
   info(`  status:        ${colorStatus(p.status)}${p.is_cold ? dim(' (cold)') : ''}`);
   info(`  url:           ${cyan(`https://${p.slug}.app.canner.ca`)}`);
@@ -415,6 +438,7 @@ async function cmdDeployments(args) {
   if (id) return viewDeployment(creds, slug, id, args.follow === true);
   const body = await apiJSON(creds, 'GET', `/projects/${encodeURIComponent(slug)}/deployments`);
   const rows = body?.deployments ?? [];
+  if (JSON_MODE) return emitJSON(rows);
   if (rows.length === 0) {
     muted('no deployments yet.');
     return;
@@ -442,6 +466,7 @@ async function viewDeployment(creds, slug, idPrefix, follow) {
   const body = await apiJSON(creds, 'GET', `/projects/${encodeURIComponent(slug)}/deployments/${fullId}`);
   const d = body?.deployment;
   if (!d) die('deployment not found');
+  if (JSON_MODE) return emitJSON(d);
   info(`${bold(d.id.slice(0, 8))}${dim(d.id.slice(8))}  ${colorStatus(d.status)}`);
   if (d.commit_sha) info(`  ${dim('commit')}  ${d.commit_sha.slice(0, 12)} ${dim((d.commit_message || '').split('\n')[0])}`);
   if (d.commit_author) info(`  ${dim('author')}  ${d.commit_author}`);
@@ -541,9 +566,233 @@ async function cmdCancel(args) {
     id = matches[0].id;
   }
   await apiJSON(creds, 'POST', `/projects/${encodeURIComponent(slug)}/deployments/${id}/cancel`);
+  if (JSON_MODE) return emitJSON({ ok: true, cancelled: id });
   info(`${green('cancelled')} ${dim(id.slice(0, 8))}`);
 }
 
+// ---------------------------------------------------------------------------
+// canner token                       — list API tokens
+// canner token create <name>         — mint a token (plaintext printed once)
+// canner token revoke <id|prefix>    — revoke a token
+// ---------------------------------------------------------------------------
+async function cmdToken(args) {
+  const creds = await loadCredentials();
+  if (!creds.token) die("not signed in. Run `canner login`.");
+  const sub = args._[0] ?? 'list';
+
+  if (sub === 'list') {
+    const body = await apiJSON(creds, 'GET', '/tokens');
+    const rows = body?.tokens ?? [];
+    if (JSON_MODE) return emitJSON(rows);
+    if (rows.length === 0) { muted('no API tokens. Create one with `canner token create <name>`.'); return; }
+    info(`${pad(bold('ID'), 12)}${pad(bold('NAME'), 28)}${pad(bold('PREFIX'), 18)}${bold('LAST USED')}`);
+    for (const t of rows) {
+      info(`${pad(dim(t.id.slice(0, 8)), 12)}${pad(t.name ?? dim('—'), 28)}${pad(dim(`${t.prefix}…`), 18)}${dim(relTime(t.last_used_at))}`);
+    }
+    return;
+  }
+
+  if (sub === 'create') {
+    const name = args._[1] || (typeof args.name === 'string' ? args.name : null);
+    if (!name) die('usage: canner token create <name>', 2);
+    const tok = await apiJSON(creds, 'POST', '/tokens', { name });
+    if (!tok?.token) die('token creation returned no secret.');
+    if (JSON_MODE) return emitJSON(tok);
+    info(`${green('created')} ${bold(tok.name)}`);
+    info(tok.token);
+    muted('Copy this now — the secret is not shown again.');
+    return;
+  }
+
+  if (sub === 'revoke') {
+    const ref = args._[1];
+    if (!ref) die('usage: canner token revoke <id|prefix|name>', 2);
+    const id = await resolveTokenId(creds, ref);
+    await apiJSON(creds, 'DELETE', `/tokens/${encodeURIComponent(id)}`);
+    if (JSON_MODE) return emitJSON({ ok: true, revoked: id });
+    info(`${green('revoked')} ${dim(id.slice(0, 8))}`);
+    return;
+  }
+
+  die(`unknown token subcommand "${sub}". Use: list | create | revoke.`, 2);
+}
+
+async function resolveTokenId(creds, ref) {
+  if (ref.length >= 36) return ref; // full UUID
+  const body = await apiJSON(creds, 'GET', '/tokens');
+  const rows = body?.tokens ?? [];
+  const matches = rows.filter(
+    (t) => t.id.startsWith(ref) || t.name === ref || (t.prefix && t.prefix.startsWith(ref))
+  );
+  if (matches.length === 0) die(`no token matching "${ref}"`);
+  if (matches.length > 1) die(`ambiguous "${ref}" — matches ${matches.length} tokens`);
+  return matches[0].id;
+}
+
+// ---------------------------------------------------------------------------
+// canner env [--slug X]                                 — list env vars
+// canner env set KEY=VALUE [--env production|preview] [--sensitive] [--slug X]
+// canner env rm <KEY|id> [--env ...] [--slug X]         — delete an env var
+// ---------------------------------------------------------------------------
+async function cmdEnv(args) {
+  const creds = await loadCredentials();
+  if (!creds.token) die("not signed in. Run `canner login`.");
+  const slug = await resolveSlug(args);
+  const sub = args._[0] ?? 'list';
+  const base = `/projects/${encodeURIComponent(slug)}/env-vars`;
+
+  if (sub === 'list') {
+    const body = await apiJSON(creds, 'GET', base);
+    const rows = body?.env_vars ?? [];
+    if (JSON_MODE) return emitJSON(rows);
+    if (rows.length === 0) { muted('no environment variables.'); return; }
+    info(`${pad(bold('KEY'), 28)}${pad(bold('ENV'), 14)}${pad(bold('SENSITIVE'), 12)}${bold('VALUE')}`);
+    for (const v of rows) {
+      const val = v.is_sensitive ? dim('••••••') : (v.value ?? '').split('\n')[0].slice(0, 48);
+      info(`${pad(v.key, 28)}${pad(dim(v.environment ?? 'all'), 14)}${pad(v.is_sensitive ? yellow('yes') : dim('no'), 12)}${dim(val)}`);
+    }
+    return;
+  }
+
+  if (sub === 'set') {
+    const kv = args._[1];
+    if (!kv || !kv.includes('=')) die('usage: canner env set KEY=VALUE', 2);
+    const eq = kv.indexOf('=');
+    const key = kv.slice(0, eq);
+    const value = kv.slice(eq + 1);
+    const environment = normalizeEnvScope(args.env);
+    const isSensitive = args.sensitive === true;
+    const result = await apiJSON(creds, 'POST', base, {
+      key, value, environment, is_sensitive: isSensitive,
+    });
+    if (JSON_MODE) return emitJSON(result);
+    if ((result?.created ?? []).length > 0) {
+      info(`${green('set')} ${bold(key)}${environment ? dim(` (${environment})`) : ''}`);
+    } else {
+      // A duplicate (same key+scope) is skipped, not overwritten — surface that
+      // so the user isn't surprised the value didn't change.
+      die(`${key} already exists for that environment. Delete it first (canner env rm ${key}), then set again.`);
+    }
+    return;
+  }
+
+  if (sub === 'rm' || sub === 'remove' || sub === 'delete') {
+    const ref = args._[1];
+    if (!ref) die('usage: canner env rm <KEY|id>', 2);
+    const id = await resolveEnvVarId(creds, base, ref, normalizeEnvScope(args.env));
+    await apiJSON(creds, 'DELETE', `${base}/${encodeURIComponent(id)}`);
+    if (JSON_MODE) return emitJSON({ ok: true, deleted: id });
+    info(`${green('deleted')} ${bold(ref)}`);
+    return;
+  }
+
+  die(`unknown env subcommand "${sub}". Use: list | set | rm.`, 2);
+}
+
+// Map a --env flag to the API's environment field. Accepts production/preview;
+// anything else (or absent) means "all environments" (null).
+function normalizeEnvScope(flag) {
+  if (flag === 'production' || flag === 'preview') return flag;
+  return null;
+}
+
+async function resolveEnvVarId(creds, base, ref, environment) {
+  if (ref.length >= 36 && ref.includes('-')) return ref; // looks like a UUID
+  const body = await apiJSON(creds, 'GET', base);
+  const rows = body?.env_vars ?? [];
+  const matches = rows.filter((v) => {
+    if (v.id.startsWith(ref)) return true;
+    if (v.key !== ref) return false;
+    // If a scope was given, narrow to it; otherwise match any scope.
+    return environment === null ? true : v.environment === environment;
+  });
+  if (matches.length === 0) die(`no env var matching "${ref}"`);
+  if (matches.length > 1) die(`ambiguous "${ref}" — matches ${matches.length} vars (pass --env to disambiguate)`);
+  return matches[0].id;
+}
+
+// ---------------------------------------------------------------------------
+// canner domains [--slug X]                  — list custom domains
+// canner domains add <hostname> [--slug X]   — attach a domain (pending)
+// canner domains verify <host|id> [--slug X] — re-check DNS + provision TLS
+// canner domains rm <host|id> [--slug X]     — detach a domain
+// ---------------------------------------------------------------------------
+async function cmdDomains(args) {
+  const creds = await loadCredentials();
+  if (!creds.token) die("not signed in. Run `canner login`.");
+  const slug = await resolveSlug(args);
+  const sub = args._[0] ?? 'list';
+  const base = `/projects/${encodeURIComponent(slug)}/domains`;
+
+  if (sub === 'list') {
+    const body = await apiJSON(creds, 'GET', base);
+    const rows = body?.domains ?? [];
+    if (JSON_MODE) return emitJSON(rows);
+    if (rows.length === 0) {
+      muted(`no custom domains. Add one with \`canner domains add <hostname>\`.`);
+      if (body?.platform_ip) muted(`Point an A record at ${body.platform_ip}, then run \`canner domains verify\`.`);
+      return;
+    }
+    info(`${pad(bold('HOSTNAME'), 36)}${pad(bold('STATUS'), 16)}${bold('VERIFIED')}`);
+    for (const d of rows) {
+      info(`${pad(d.hostname, 36)}${pad(colorDomainStatus(d.status), 16)}${dim(relTime(d.verified_at))}`);
+    }
+    if (body?.platform_ip) muted(`A record target: ${body.platform_ip}`);
+    return;
+  }
+
+  if (sub === 'add') {
+    const hostname = args._[1];
+    if (!hostname) die('usage: canner domains add <hostname>', 2);
+    const body = await apiJSON(creds, 'POST', base, { hostname });
+    if (JSON_MODE) return emitJSON(body);
+    const d = body?.domain ?? {};
+    info(`${green('added')} ${bold(d.hostname ?? hostname)} ${dim(`(${d.status ?? 'pending'})`)}`);
+    if (body?.platform_ip) muted(`Point an A record at ${body.platform_ip}, then run \`canner domains verify ${hostname}\`.`);
+    return;
+  }
+
+  if (sub === 'verify') {
+    const ref = args._[1];
+    if (!ref) die('usage: canner domains verify <hostname|id>', 2);
+    const id = await resolveDomainId(creds, base, ref);
+    const body = await apiJSON(creds, 'POST', `${base}/${encodeURIComponent(id)}/verify`);
+    if (JSON_MODE) return emitJSON(body);
+    const d = body?.domain ?? {};
+    info(`${green('verified')} ${bold(d.hostname ?? ref)} ${dim(`(${d.status ?? 'verified'})`)}`);
+    return;
+  }
+
+  if (sub === 'rm' || sub === 'remove' || sub === 'delete') {
+    const ref = args._[1];
+    if (!ref) die('usage: canner domains rm <hostname|id>', 2);
+    const id = await resolveDomainId(creds, base, ref);
+    await apiJSON(creds, 'DELETE', `${base}/${encodeURIComponent(id)}`);
+    if (JSON_MODE) return emitJSON({ ok: true, deleted: id });
+    info(`${green('removed')} ${bold(ref)}`);
+    return;
+  }
+
+  die(`unknown domains subcommand "${sub}". Use: list | add | verify | rm.`, 2);
+}
+
+function colorDomainStatus(s) {
+  if (s === 'verified') return green(s);
+  if (s === 'failed') return red(s);
+  if (s === 'pending') return yellow(s);
+  return dim(s);
+}
+
+async function resolveDomainId(creds, base, ref) {
+  if (ref.length >= 36 && ref.includes('-')) return ref; // UUID
+  const body = await apiJSON(creds, 'GET', base);
+  const rows = body?.domains ?? [];
+  const matches = rows.filter((d) => d.id.startsWith(ref) || d.hostname === ref);
+  if (matches.length === 0) die(`no domain matching "${ref}"`);
+  if (matches.length > 1) die(`ambiguous "${ref}" — matches ${matches.length} domains`);
+  return matches[0].id;
+}
+
 // ---------------------------------------------------------------------------
 // canner open [--slug X] [--dashboard]
 //   Open the tenant URL (default) or the dashboard project page in the
@@ -587,6 +836,7 @@ async function cmdRedeploy(args) {
   const body = await res.json();
   const deploymentId = body.deployment_id;
   if (!deploymentId) die('redeploy returned no deployment_id.');
+  if (JSON_MODE) return emitJSON({ deployment_id: deploymentId, status: body.status ?? 'queued', slug });
   info(`${green('queued')} deployment ${dim(deploymentId.slice(0, 8))}  ${dim('(rebuild from GitHub HEAD)')}`);
   if (!args.follow) {
     muted(`Tail with: canner deployments ${deploymentId.slice(0, 8)} --follow`);
@@ -684,6 +934,12 @@ async function cmdDeploy(args) {
   if (!deploymentId) {
     die('upload succeeded but the response had no deployment_id.');
   }
+  if (JSON_MODE) {
+    // JSON mode never streams the SSE build log (it would corrupt the
+    // single-value contract). Emit the queued result; the caller can poll
+    // `canner deployments <id> --json` for terminal status.
+    return emitJSON({ deployment_id: deploymentId, status: body.status ?? 'queued', slug, files: fileCount, size_mb: Number(sizeMb) });
+  }
   info(`${green('queued')} deployment ${dim(deploymentId.slice(0, 8))}`);
 
   if (!args.follow) {
@@ -849,6 +1105,24 @@ ${bold('Deploys:')}
                        Stream the running tenant's runtime logs (last 200
                        lines by default, --follow to keep streaming).
 
+${bold('Resources:')}
+  ${bold('token')} list | create <name> | revoke <id|name>
+                       Manage the cnr_ API tokens that authenticate this CLI.
+  ${bold('env')} [list] [--slug X]
+  ${bold('env')} set KEY=VALUE [--env production|preview] [--sensitive] [--slug X]
+  ${bold('env')} rm <KEY|id> [--env ...] [--slug X]
+                       Manage a project's environment variables.
+  ${bold('domains')} [list] [--slug X]
+  ${bold('domains')} add <hostname> [--slug X]
+  ${bold('domains')} verify <hostname|id> [--slug X]
+  ${bold('domains')} rm <hostname|id> [--slug X]
+                       Manage a project's custom domains.
+
+${bold('Global:')}
+  ${bold('--json')}               Emit machine-readable JSON (for scripts, CI, agents).
+                       Suppresses tables + progress; --follow log streaming is
+                       skipped. Errors go to stderr as {"error":"..."}.
+
 ${bold('Examples:')}
   canner login
   cd my-site && canner init
@@ -859,6 +1133,10 @@ ${bold('Examples:')}
   canner logs --follow                    ${dim('# tail tenant runtime logs')}
   canner cancel                            ${dim('# abort the current build')}
   canner open --dashboard                 ${dim('# open dashboard project page')}
+  canner token create ci                  ${dim('# mint a token named "ci"')}
+  canner env set API_KEY=secret --sensitive  ${dim('# add a hidden env var')}
+  canner domains add www.example.com      ${dim('# attach a custom domain')}
+  canner projects --json | jq '.[].slug'  ${dim('# machine-readable output')}
 
 ${bold('Environment:')}
   CANNER_TOKEN         Override stored token (handy for CI).
@@ -882,6 +1160,10 @@ Version: ${VERSION}
 const args = parseArgs(process.argv.slice(2));
 const command = args._.shift();
 
+// Global --json: machine-readable output for scripts, CI, and agents. Set
+// before dispatch so every helper (info/muted/die) honors it.
+JSON_MODE = args.json === true;
+
 if (args.version || args.v || command === 'version') {
   process.stdout.write(`canner ${VERSION}\n`);
   process.exit(0);
@@ -903,6 +1185,10 @@ const dispatch = {
   deployments: cmdDeployments,
   cancel: cmdCancel,
   open: cmdOpen,
+  token: cmdToken,
+  tokens: cmdToken,
+  env: cmdEnv,
+  domains: cmdDomains,
 };
 const handler = dispatch[command];
 if (!handler) {