novence 0.0.1 → 0.1.0

package/README.md

@@ -51,11 +51,21 @@ URL=$(novence deploy ./dist)
 ## Other commands
 
 ```bash
-novence login       # sign in, verify email, or recover a key with --recover
-novence projects    # list projects and their URLs
-novence whoami      # plan, verification, usage against quota
+novence open [project]        # open the live URL in a browser
+novence checks [project]      # Lighthouse / axe / link results for the last deploy
+novence domains add <host>    # attach a custom domain, prints the DNS records
+novence domains status        # custom domain state
+novence keys list             # API keys on the account
+novence keys revoke <id>      # revoke a key (--force to revoke the one in use)
+novence projects              # list projects and their URLs
+novence login                 # sign in, verify email, or --recover a key
+novence whoami                # plan, verification, usage against quota
 ```
 
+Every command accepts `--json`. Unknown flags are rejected rather than ignored,
+so a typo like `--nmae` fails loudly instead of silently deploying under the
+default name.
+
 ## For agents and CI
 
 `--json` gives a stable envelope and exits non-zero on failure:

package/dist/commands/checks.d.ts

@@ -0,0 +1,2 @@
+import { type ParsedArgs } from "../lib/args.js";
+export declare function checksCommand(args: ParsedArgs): Promise<void>;

package/dist/commands/checks.js

@@ -0,0 +1,69 @@
+import { Novence } from "@novence/sdk";
+import { loadApiKey, resolveApiBase } from "../lib/config.js";
+import { flagString } from "../lib/args.js";
+import { explain } from "../lib/errors.js";
+import { fail, isJsonMode, json, result } from "../lib/ui.js";
+function pct(value) {
+    return typeof value === "number" ? String(Math.round(value)) : "—";
+}
+export async function checksCommand(args) {
+    const apiBase = resolveApiBase(flagString(args.flags, "api"));
+    const apiKey = loadApiKey();
+    if (!apiKey)
+        fail("Not signed in. Run `novence login`.");
+    const client = new Novence({ apiKey, baseUrl: apiBase });
+    const wanted = args.positionals[0];
+    let projectId = wanted;
+    try {
+        if (!projectId) {
+            const { projects } = await client.projects.list();
+            if (projects.length === 0)
+                fail("No projects yet. Run `novence deploy ./dist`.");
+            projectId = projects[0].id;
+        }
+        const { deployment } = await client.deployments.latest(projectId);
+        const checks = deployment.checksResults;
+        if (isJsonMode()) {
+            json({ ok: true, projectId, status: deployment.status, checks: checks ?? null });
+            return;
+        }
+        result(`deployment  ${deployment.id}`);
+        result(`status      ${deployment.status}`);
+        if (deployment.errorMessage)
+            result(`error       ${deployment.errorMessage}`);
+        if (!checks) {
+            result("checks      not available for this deployment");
+            return;
+        }
+        if (checks.skipped) {
+            result(`checks      skipped${checks.reason ? ` (${checks.reason})` : ""}`);
+            result("            Verify your email to enable checks: novence login");
+            return;
+        }
+        result(`checks      ${checks.passed === true ? "passed" : checks.passed === false ? "FAILED" : "unknown"}`);
+        const lh = checks.lighthouse;
+        if (lh) {
+            result(`lighthouse  perf ${pct(lh.performance)}  a11y ${pct(lh.accessibility)}  ` +
+                `seo ${pct(lh.seo)}  best-practices ${pct(lh.bestPractices)}`);
+        }
+        const axe = checks.axe;
+        if (axe) {
+            result(`axe         critical ${axe.critical ?? 0}  serious ${axe.serious ?? 0}  ` +
+                `moderate ${axe.moderate ?? 0}  minor ${axe.minor ?? 0}`);
+        }
+        const links = checks.links;
+        if (links) {
+            result(`links       ${links.checked ?? 0} checked, ${(links.broken ?? []).length} broken`);
+        }
+        if (deployment.checksUrl) {
+            // The API returns a path; make it something you can actually open.
+            const url = deployment.checksUrl.startsWith("http")
+                ? deployment.checksUrl
+                : `${apiBase}${deployment.checksUrl}`;
+            result(`report      ${url}`);
+        }
+    }
+    catch (err) {
+        fail(explain(err, { apiBase, projectId: wanted }));
+    }
+}

package/dist/commands/deploy.js

@@ -4,7 +4,8 @@ import { Novence } from "@novence/sdk";
 import { ensureApiKey } from "../lib/auth.js";
 import { resolveApiBase } from "../lib/config.js";
 import { flagBool, flagString } from "../lib/args.js";
-import { fail, isJsonMode, json, result, step, warn } from "../lib/ui.js";
+import { fail, isJsonMode, json, result, siteUrl, step, warn } from "../lib/ui.js";
+import { explain } from "../lib/errors.js";
 const POLL_INTERVAL_MS = 2000;
 const POLL_TIMEOUT_MS = 5 * 60 * 1000;
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
@@ -60,6 +61,15 @@ export async function deployCommand(args) {
     if (!existsSync(resolve(siteDir, "index.html"))) {
         fail(`${siteDir} has no index.html — a static site needs one at its root.`);
     }
+    let projectId = flagString(args.flags, "project");
+    try {
+        await runDeploy(args, apiBase, siteDir);
+    }
+    catch (err) {
+        fail(explain(err, { apiBase, projectId }));
+    }
+}
+async function runDeploy(args, apiBase, siteDir) {
     const { apiKey } = await ensureApiKey({
         apiBase,
         email: flagString(args.flags, "email"),
@@ -67,17 +77,17 @@ export async function deployCommand(args) {
     });
     const client = new Novence({ apiKey, baseUrl: apiBase });
     let projectId = flagString(args.flags, "project");
-    let siteUrl;
+    let projectUrl;
     if (projectId) {
         const { project } = await client.projects.get(projectId);
-        siteUrl = project.url;
+        projectUrl = project.url;
         step(`Reusing project ${project.name} (${project.suffix})`);
     }
     else {
         const name = flagString(args.flags, "name") ?? "site";
         const created = await client.projects.create({ name });
         projectId = created.project.id;
-        siteUrl = created.url;
+        projectUrl = created.url;
         step(`Created project ${name} (${created.project.suffix})`);
     }
     step(`Uploading ${siteDir}…`);
@@ -93,7 +103,7 @@ export async function deployCommand(args) {
         fail(deployment.errorMessage ?? "Deploy failed.");
     }
     reportChecks(deployment);
-    const liveUrl = (deployment.liveUrl ?? siteUrl).replace(/\/?$/, "/");
+    const liveUrl = siteUrl(deployment.liveUrl ?? projectUrl);
     if (isJsonMode()) {
         json({
             ok: true,

package/dist/commands/domains.d.ts

@@ -0,0 +1,2 @@
+import { type ParsedArgs } from "../lib/args.js";
+export declare function domainsCommand(args: ParsedArgs): Promise<void>;

package/dist/commands/domains.js

@@ -0,0 +1,84 @@
+import { Novence } from "@novence/sdk";
+import { loadApiKey, resolveApiBase } from "../lib/config.js";
+import { flagString } from "../lib/args.js";
+import { explain } from "../lib/errors.js";
+import { fail, isJsonMode, json, result, step } from "../lib/ui.js";
+async function resolveProjectId(client, explicit) {
+    if (explicit)
+        return explicit;
+    const { projects } = await client.projects.list();
+    if (projects.length === 0)
+        fail("No projects yet. Run `novence deploy ./dist` first.");
+    if (projects.length > 1) {
+        fail("You have more than one project — say which:\n" +
+            "  novence domains add <hostname> --project <id>\n" +
+            "  novence projects");
+    }
+    return projects[0].id;
+}
+export async function domainsCommand(args) {
+    const apiBase = resolveApiBase(flagString(args.flags, "api"));
+    const apiKey = loadApiKey();
+    if (!apiKey)
+        fail("Not signed in. Run `novence login`.");
+    const client = new Novence({ apiKey, baseUrl: apiBase });
+    const sub = args.positionals[0] ?? "status";
+    const projectFlag = flagString(args.flags, "project");
+    try {
+        if (sub === "add") {
+            const hostname = args.positionals[1];
+            if (!hostname) {
+                fail("Usage: novence domains add <hostname> [--project <id>] [--primary www|apex]");
+            }
+            const projectId = await resolveProjectId(client, projectFlag);
+            const res = await client.domains.configure(projectId, hostname);
+            if (isJsonMode()) {
+                json({ ok: true, projectId, hostname, ...res });
+                return;
+            }
+            step(`Attached ${hostname}`);
+            const records = res.instructions?.records ?? [];
+            if (records.length === 0) {
+                result("No DNS records returned — check `novence domains status`.");
+                return;
+            }
+            result("");
+            result("Create these DNS records at your registrar:");
+            result("");
+            for (const rec of records) {
+                const type = String(rec.type ?? "?");
+                const name = String(rec.name ?? rec.host ?? "@");
+                const target = String(rec.target ?? rec.value ?? "");
+                result(`  ${type.padEnd(14)} ${name.padEnd(20)} ${target}`);
+            }
+            result("");
+            result("Then check propagation with:  novence domains status");
+            return;
+        }
+        if (sub === "status") {
+            const projectId = await resolveProjectId(client, projectFlag);
+            const status = await client.domains.status(projectId);
+            if (isJsonMode()) {
+                json({ ok: true, projectId, ...status });
+                return;
+            }
+            const host = status.customDomain ?? status.hostname;
+            if (!host) {
+                result("No custom domain attached.");
+                result("  Attach one with:  novence domains add <hostname>");
+                return;
+            }
+            result(`domain  ${host}`);
+            result(`status  ${status.customDomainStatus ?? status.status ?? "unknown"}`);
+            const verifications = status.verifications;
+            if (Array.isArray(verifications) && verifications.length > 0) {
+                result(`checks  ${verifications.length} verification record(s) pending or done`);
+            }
+            return;
+        }
+        fail(`Unknown subcommand: ${sub}\n  Usage: novence domains add <hostname> | novence domains status`);
+    }
+    catch (err) {
+        fail(explain(err, { apiBase, projectId: projectFlag }));
+    }
+}

package/dist/commands/keys.d.ts

@@ -0,0 +1,2 @@
+import { type ParsedArgs } from "../lib/args.js";
+export declare function keysCommand(args: ParsedArgs): Promise<void>;

package/dist/commands/keys.js

@@ -0,0 +1,56 @@
+import { Novence } from "@novence/sdk";
+import { loadApiKey, resolveApiBase } from "../lib/config.js";
+import { flagBool, flagString } from "../lib/args.js";
+import { explain } from "../lib/errors.js";
+import { fail, isJsonMode, json, result, step } from "../lib/ui.js";
+export async function keysCommand(args) {
+    const apiBase = resolveApiBase(flagString(args.flags, "api"));
+    const apiKey = loadApiKey();
+    if (!apiKey)
+        fail("Not signed in. Run `novence login`.");
+    const client = new Novence({ apiKey, baseUrl: apiBase });
+    const sub = args.positionals[0] ?? "list";
+    try {
+        if (sub === "list") {
+            const { keys } = await client.apiKeys.list({
+                projectId: flagString(args.flags, "project"),
+                includeRevoked: flagBool(args.flags, "include-revoked"),
+            });
+            if (isJsonMode()) {
+                json({ ok: true, keys });
+                return;
+            }
+            if (keys.length === 0) {
+                result("No keys.");
+                return;
+            }
+            const w = Math.max(...keys.map((k) => k.name.length), 4);
+            for (const k of keys) {
+                const marks = [k.current ? "current" : "", k.revokedAt ? "revoked" : ""]
+                    .filter(Boolean)
+                    .join(", ");
+                result(`${k.keyPrefix}  ${k.name.padEnd(w)}  ${k.scope.padEnd(7)}  ${k.id}${marks ? `  (${marks})` : ""}`);
+            }
+            return;
+        }
+        if (sub === "revoke") {
+            const id = args.positionals[1];
+            if (!id)
+                fail("Usage: novence keys revoke <id> [--force]\n  Find ids with:  novence keys list");
+            const force = flagBool(args.flags, "force");
+            const res = await client.apiKeys.revoke(id, { force });
+            if (isJsonMode()) {
+                json({ ok: true, ...res });
+                return;
+            }
+            result(`Revoked ${id}`);
+            if (force)
+                step("That was the key this machine uses — run `novence login` to get a new one.");
+            return;
+        }
+        fail(`Unknown subcommand: ${sub}\n  Usage: novence keys list | novence keys revoke <id>`);
+    }
+    catch (err) {
+        fail(explain(err, { apiBase }));
+    }
+}

package/dist/commands/open.d.ts

@@ -0,0 +1,2 @@
+import { type ParsedArgs } from "../lib/args.js";
+export declare function openCommand(args: ParsedArgs): Promise<void>;

package/dist/commands/open.js

@@ -0,0 +1,51 @@
+import { spawn } from "node:child_process";
+import { Novence } from "@novence/sdk";
+import { loadApiKey, resolveApiBase } from "../lib/config.js";
+import { flagString } from "../lib/args.js";
+import { explain } from "../lib/errors.js";
+import { fail, isJsonMode, json, result, siteUrl, step } from "../lib/ui.js";
+/** Platform opener; falls back to printing the URL when there is no GUI. */
+function openInBrowser(url) {
+    const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+    try {
+        const child = spawn(cmd, [url], { stdio: "ignore", detached: true });
+        child.unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function openCommand(args) {
+    const apiBase = resolveApiBase(flagString(args.flags, "api"));
+    const apiKey = loadApiKey();
+    if (!apiKey)
+        fail("Not signed in. Run `novence login`.");
+    const client = new Novence({ apiKey, baseUrl: apiBase });
+    const wanted = args.positionals[0];
+    try {
+        const { projects } = await client.projects.list();
+        if (projects.length === 0) {
+            fail("No projects yet. Run `novence deploy ./dist` to create one.");
+        }
+        // Match on id, suffix, or name so any of them works.
+        const project = wanted
+            ? projects.find((p) => p.id === wanted || p.suffix === wanted || p.name === wanted)
+            : projects[0];
+        if (!project) {
+            fail(`No project matching "${wanted}".\n  List them with:  novence projects`);
+        }
+        if (isJsonMode()) {
+            json({ ok: true, projectId: project.id, url: siteUrl(project.url) });
+            return;
+        }
+        const target = siteUrl(project.url);
+        const opened = openInBrowser(target);
+        if (!opened)
+            step("Could not launch a browser — the URL is below.");
+        result(target);
+    }
+    catch (err) {
+        fail(explain(err, { apiBase }));
+    }
+}

package/dist/index.js

@@ -2,20 +2,32 @@
 import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { flagBool, parseArgs } from "./lib/args.js";
+import { assertKnownFlags, flagBool, flagString, parseArgs } from "./lib/args.js";
+import { resolveApiBase } from "./lib/config.js";
+import { explain } from "./lib/errors.js";
 import { fail, isJsonMode, result, setJsonMode } from "./lib/ui.js";
 import { deployCommand } from "./commands/deploy.js";
 import { loginCommand } from "./commands/login.js";
 import { projectsCommand } from "./commands/projects.js";
 import { whoamiCommand } from "./commands/whoami.js";
+import { openCommand } from "./commands/open.js";
+import { domainsCommand } from "./commands/domains.js";
+import { keysCommand } from "./commands/keys.js";
+import { checksCommand } from "./commands/checks.js";
 const HELP = `
   novence — deploy a static site to the edge
 
   Usage
     novence deploy [dir]        Upload a directory and publish it live
+    novence open [project]      Open a project's live URL
+    novence checks [project]    Quality-gate results for the latest deploy
+    novence domains add <host>  Attach a custom domain (prints DNS records)
+    novence domains status      Custom domain state
+    novence keys list           API keys on the account
+    novence keys revoke <id>    Revoke a key
+    novence projects            List projects and their URLs
     novence login               Sign in, verify email, or recover a key
-    novence projects            List your projects and their URLs
-    novence whoami              Show plan, verification, and usage
+    novence whoami              Plan, verification, and usage
 
   Deploy
     novence deploy              Auto-detects dist, build, out, public, _site
@@ -56,9 +68,36 @@ async function main() {
         process.stdout.write(HELP);
         return;
     }
+    // Per-command flag allowlists — a typo should fail loudly, not silently
+    // change behaviour.
+    const ALLOWED = {
+        deploy: ["name", "project", "email"],
+        open: [],
+        checks: [],
+        domains: ["project", "primary", "redirect"],
+        keys: ["project", "include-revoked", "force"],
+        projects: [],
+        ls: [],
+        login: ["email", "recover"],
+        whoami: [],
+    };
+    const allowed = ALLOWED[args.command];
+    if (allowed) {
+        const problem = assertKnownFlags(args.flags, allowed, args.command);
+        if (problem)
+            fail(problem);
+    }
     switch (args.command) {
         case "deploy":
             return deployCommand(args);
+        case "open":
+            return openCommand(args);
+        case "checks":
+            return checksCommand(args);
+        case "domains":
+            return domainsCommand(args);
+        case "keys":
+            return keysCommand(args);
         case "login":
             return loginCommand(args);
         case "projects":
@@ -71,5 +110,7 @@ async function main() {
     }
 }
 main().catch((err) => {
-    fail(err instanceof Error ? err.message : String(err));
+    // Last-resort handler; commands that know a projectId explain it themselves.
+    const apiBase = resolveApiBase(flagString(parseArgs(process.argv.slice(2)).flags, "api"));
+    fail(explain(err, { apiBase }));
 });

package/dist/lib/args.d.ts

@@ -7,3 +7,11 @@ export interface ParsedArgs {
 export declare function parseArgs(argv: string[]): ParsedArgs;
 export declare function flagString(flags: ParsedArgs["flags"], name: string): string | undefined;
 export declare function flagBool(flags: ParsedArgs["flags"], name: string): boolean;
+/** Flags every command accepts. */
+export declare const GLOBAL_FLAGS: string[];
+/**
+ * Reject unrecognised flags. Without this a typo like `--nmae "My Site"` is
+ * silently dropped and the user gets a differently-named project with no
+ * explanation.
+ */
+export declare function assertKnownFlags(flags: ParsedArgs["flags"], allowed: string[], command: string): string | null;

package/dist/lib/args.js

@@ -40,3 +40,20 @@ export function flagString(flags, name) {
 export function flagBool(flags, name) {
     return flags[name] === true || flags[name] === "true";
 }
+/** Flags every command accepts. */
+export const GLOBAL_FLAGS = ["json", "no-input", "api", "help", "version", "quiet"];
+/**
+ * Reject unrecognised flags. Without this a typo like `--nmae "My Site"` is
+ * silently dropped and the user gets a differently-named project with no
+ * explanation.
+ */
+export function assertKnownFlags(flags, allowed, command) {
+    const known = new Set([...allowed, ...GLOBAL_FLAGS]);
+    const unknown = Object.keys(flags).filter((f) => !known.has(f));
+    if (unknown.length === 0)
+        return null;
+    const valid = [...allowed, ...GLOBAL_FLAGS].sort().map((f) => `--${f}`).join(" ");
+    return (`Unknown ${unknown.length > 1 ? "flags" : "flag"} for \`novence ${command}\`: ` +
+        unknown.map((f) => `--${f}`).join(", ") +
+        `\n  Valid flags: ${valid}`);
+}

package/dist/lib/errors.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Turn an SDK error into something a user can act on. Every branch names the
+ * next command to run — a bare "Unauthorized" tells nobody anything.
+ */
+export declare function explain(err: unknown, ctx: {
+    apiBase: string;
+    projectId?: string;
+}): string;

package/dist/lib/errors.js

@@ -0,0 +1,57 @@
+import { NovenceError } from "@novence/sdk";
+/** Node wraps connection failures in a TypeError with the real cause nested. */
+function networkCause(err) {
+    if (!(err instanceof Error))
+        return null;
+    const cause = err.cause;
+    const code = cause?.code;
+    if (code)
+        return code;
+    return /fetch failed|ECONNREFUSED|ENOTFOUND|ETIMEDOUT|EAI_AGAIN/i.test(err.message)
+        ? "ECONNREFUSED"
+        : null;
+}
+/**
+ * Turn an SDK error into something a user can act on. Every branch names the
+ * next command to run — a bare "Unauthorized" tells nobody anything.
+ */
+export function explain(err, ctx) {
+    const net = networkCause(err);
+    if (net) {
+        const hint = net === "ENOTFOUND" || net === "EAI_AGAIN"
+            ? "The host could not be resolved — check the URL and your DNS."
+            : "Nothing is listening there — check the URL, or your network/VPN.";
+        return `Cannot reach the Novence API at ${ctx.apiBase} (${net}).\n  ${hint}`;
+    }
+    if (err instanceof NovenceError) {
+        const { message: detail, status } = err;
+        switch (status) {
+            case 401:
+            case 403:
+                return (`${detail}\n` +
+                    "  Your API key was rejected. It may be revoked, or from another environment.\n" +
+                    "  Sign in again:  novence login");
+            case 402:
+                return (`${detail}\n` +
+                    "  Redeploy an existing project instead:  novence deploy --project <id>\n" +
+                    "  List what you have:                    novence projects\n" +
+                    "  Or raise your limits:                  https://novence.ai/pricing");
+            case 404:
+                return ctx.projectId
+                    ? `Project ${ctx.projectId} not found on this account.\n` +
+                        "  Check the id with:  novence projects"
+                    : `${detail}\n  The requested resource does not exist on this account.`;
+            case 409:
+                return detail;
+            case 429:
+                return `${detail}\n  You are being rate limited. Wait a minute and retry.`;
+            default:
+                if (status >= 500) {
+                    return (`${detail} (HTTP ${status})\n` +
+                        "  The API returned a server error. Check https://novence.ai/status and retry.");
+                }
+                return detail;
+        }
+    }
+    return err instanceof Error ? err.message : String(err);
+}

package/dist/lib/ui.d.ts

@@ -8,3 +8,5 @@ export declare function result(value: string): void;
 export declare function json(value: unknown): void;
 export declare function fail(message: string): never;
 export declare function prompt(question: string): Promise<string>;
+/** Canonical site URL shape — always one trailing slash, everywhere. */
+export declare function siteUrl(url: string): string;

package/dist/lib/ui.js

@@ -46,3 +46,7 @@ export async function prompt(question) {
 function stderr() {
     return process.stderr;
 }
+/** Canonical site URL shape — always one trailing slash, everywhere. */
+export function siteUrl(url) {
+    return url.replace(/\/?$/, "/");
+}

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "novence",
-  "version": "0.0.1",
-  "description": "CLI for Novence — deploy a static site to the edge in one command.",
+  "version": "0.1.0",
+  "description": "CLI for Novence \u2014 deploy a static site to the edge in one command.",
   "license": "MIT",
   "type": "module",
   "bin": {
-    "novence": "./dist/index.js"
+    "novence": "dist/index.js"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -40,7 +40,7 @@
     "prepublishOnly": "pnpm run build"
   },
   "dependencies": {
-    "@novence/sdk": "^0.1.0"
+    "@novence/sdk": "^0.2.2"
   },
   "devDependencies": {
     "@types/node": "^22.10.2",