novence 0.0.2 → 0.1.1

package/README.md

@@ -1,15 +1,23 @@
 # novence
 
-Deploy a static site to the edge in one command.
+Deploy a static site to the edge in one command. Prints the live URL. No email
+until you claim.
 
 ```bash
 npx novence deploy ./dist
 ```
 
+```text
+  Created project site (abcd1234)
+  Uploaded 12 files
+  https://abcd1234.novence.ai/
+```
+
 Uploads the directory, runs quality checks (Lighthouse, axe, links), publishes to
 `https://{suffix}.novence.ai/`, and prints the live URL.
 
 Part of [Novence](https://novence.ai) — static site hosting built for AI agents.
+Same loop as the homepage kit: Copy Prompt · email OTP · or `npx novence deploy`.
 
 ## Install
 
@@ -28,8 +36,18 @@ novence deploy              # auto-detects dist, build, out, public, _site
 novence deploy ./site       # or point at a directory
 ```
 
-First run asks for an email and a 6-digit code, then stores your API key in
-`~/.novence/credentials` (mode 0600). After that, deploys are one command.
+First run with no stored key publishes anonymously (no email), stores
+`~/.novence/credentials` (mode 0600), and prints the live URL. Claim afterwards:
+
+```bash
+novence claim --email you@example.com
+```
+
+Or pass `--email` on first deploy to bootstrap instead of the demo path:
+
+```bash
+novence deploy ./dist --email you@example.com
+```
 
 The live URL is the last line on stdout and progress goes to stderr, so it pipes:
 
@@ -43,7 +61,7 @@ URL=$(novence deploy ./dist)
 | --- | --- |
 | `--name <name>` | Project name (default `site`) |
 | `--project <id>` | Redeploy an existing project instead of creating one |
-| `--email <email>` | Skip the email prompt on first run |
+| `--email <email>` | Bootstrap with email on first deploy instead of anonymous |
 | `--json` | Machine-readable output; implies `--no-input` |
 | `--no-input` | Never prompt — fail instead. For CI |
 | `--api <url>` | Control plane (default `https://api.novence.ai`) |
@@ -51,12 +69,35 @@ 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 claim                 # attach an email to an anonymous deploy
+novence whoami                # plan, verification, usage against quota
 ```
 
-## For agents and CI
+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
+
+When a shell is available, prefer the CLI over MCP or raw REST:
+
+```bash
+npx novence deploy ./dist
+novence claim --email you@example.com
+```
+
+Copy Prompt kit (same loop, pasteable): [novence.ai](https://novence.ai).
+Full agent brief: [novence.ai/llms-full.txt](https://novence.ai/llms-full.txt).
+
+## For CI
 
 `--json` gives a stable envelope and exits non-zero on failure:
 
@@ -72,7 +113,7 @@ novence whoami      # plan, verification, usage against quota
 }
 ```
 
-In CI, set `NOVENCE_API_KEY` and pass `--no-input`.
+Set `NOVENCE_API_KEY` and pass `--no-input`.
 
 Key lookup order: `NOVENCE_API_KEY`, then `./.novence-key`, then
 `~/.novence/credentials`. Never commit a key.
@@ -81,17 +122,11 @@ Key lookup order: `NOVENCE_API_KEY`, then `./.novence-key`, then
 
 Deploys run Lighthouse, axe, and link checks. On unverified accounts checks are
 skipped — `checks.skipped` is `true` and `checks.passed` is `null`, which is not
-a pass. Verify your email with `novence login` to enable them.
-
-## Roadmap
-
-Today the first deploy requires an email up front. Once anonymous deploys land in
-the API, `novence deploy` will publish first and let you claim the site
-afterwards — no signup before you see a URL.
+a pass. Verify your email with `novence login` (or claim) to enable them.
 
 ## Docs
 
-[Documentation](https://novence.ai/docs) · [Pricing](https://novence.ai/pricing) · [TypeScript SDK](https://www.npmjs.com/package/@novence/sdk) · [MCP server](https://novence.ai/mcp)
+[CLI reference](https://novence.ai/cli) · [Documentation](https://novence.ai/docs) · [Pricing](https://novence.ai/pricing) · [TypeScript SDK](https://www.npmjs.com/package/@novence/sdk) · [MCP server](https://novence.ai/mcp)
 
 ## License
 

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/claim.d.ts

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

package/dist/commands/claim.js

@@ -0,0 +1,16 @@
+import { loadApiKey, resolveApiBase } from "../lib/config.js";
+import { claimAndMaybeVerify } from "../lib/auth.js";
+import { flagBool, flagString } from "../lib/args.js";
+import { fail, isJsonMode, prompt, result } from "../lib/ui.js";
+export async function claimCommand(args) {
+    const apiBase = resolveApiBase(flagString(args.flags, "api"));
+    const apiKey = loadApiKey();
+    if (!apiKey)
+        fail("No API key. Deploy once (`novence deploy`) or set NOVENCE_API_KEY.");
+    const interactive = !isJsonMode() && !flagBool(args.flags, "no-input");
+    const email = flagString(args.flags, "email") ?? (interactive ? await prompt("  Email: ") : "");
+    if (!email)
+        fail("Email required. Use `--email you@example.com`.");
+    await claimAndMaybeVerify({ apiKey, apiBase, email, interactive });
+    result(`Claimed ${email}. Verify if you have not already.`);
+}

package/dist/commands/deploy.js

@@ -1,10 +1,11 @@
 import { existsSync, statSync } from "node:fs";
 import { resolve } from "node:path";
 import { Novence } from "@novence/sdk";
-import { ensureApiKey } from "../lib/auth.js";
+import { claimAndMaybeVerify, 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, prompt, result, siteUrl, spin, step, warn, withSpin } 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));
@@ -25,19 +26,34 @@ function resolveSiteDir(explicit) {
     return fail(`No build output found. Looked for ${CANDIDATE_DIRS.join(", ")} in ${process.cwd()}.\n` +
         "  Pass one explicitly:  novence deploy ./your-dir");
 }
-async function waitForLive(client, projectId) {
+async function publish(client, projectId) {
+    const spinner = spin("Publishing…");
     const startedAt = Date.now();
-    let lastStatus = "";
-    while (Date.now() - startedAt < POLL_TIMEOUT_MS) {
-        const { deployment } = await client.deployments.latest(projectId);
-        if (deployment.status !== lastStatus) {
-            step(`${deployment.status}…`);
-            lastStatus = deployment.status;
+    try {
+        await client.deployments.create(projectId);
+        let lastStatus = "";
+        while (Date.now() - startedAt < POLL_TIMEOUT_MS) {
+            const { deployment } = await client.deployments.latest(projectId);
+            if (deployment.status !== lastStatus) {
+                spinner.update(`${deployment.status}…`);
+                lastStatus = deployment.status;
+            }
+            if (deployment.status === "live") {
+                spinner.stop("Live");
+                return deployment;
+            }
+            if (deployment.status === "failed") {
+                spinner.stop();
+                return deployment;
+            }
+            await sleep(POLL_INTERVAL_MS);
         }
-        if (deployment.status === "live" || deployment.status === "failed")
-            return deployment;
-        await sleep(POLL_INTERVAL_MS);
     }
+    catch (err) {
+        spinner.stop();
+        throw err;
+    }
+    spinner.stop();
     return fail("Timed out after 5 minutes waiting for the deploy to go live.");
 }
 function reportChecks(deployment) {
@@ -60,31 +76,38 @@ 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.`);
     }
-    const { apiKey } = await ensureApiKey({
+    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 interactive = !isJsonMode() && !flagBool(args.flags, "no-input");
+    const creds = await ensureApiKey({
         apiBase,
         email: flagString(args.flags, "email"),
-        interactive: !isJsonMode() && !flagBool(args.flags, "no-input"),
+        interactive,
     });
-    const client = new Novence({ apiKey, baseUrl: apiBase });
+    const client = new Novence({ apiKey: creds.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}…`);
-    const { uploaded } = await client.files.uploadDir(projectId, siteDir);
-    step(`Uploaded ${uploaded.length} file${uploaded.length === 1 ? "" : "s"}`);
-    await client.deployments.create(projectId);
-    const deployment = await waitForLive(client, projectId);
+    const { uploaded } = await withSpin(`Uploading ${siteDir}…`, () => client.files.uploadDir(projectId, siteDir), ({ uploaded: files }) => `Uploaded ${files.length} file${files.length === 1 ? "" : "s"}`);
+    const deployment = await publish(client, projectId);
     if (deployment.status === "failed") {
         if (isJsonMode()) {
             json({ ok: false, projectId, status: deployment.status, error: deployment.errorMessage });
@@ -93,7 +116,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,
@@ -108,4 +131,10 @@ export async function deployCommand(args) {
     }
     // Last line, alone, so it pipes cleanly.
     result(liveUrl);
+    if (creds.anonymous && interactive) {
+        warn("Claim this site to keep it past 30 days and unlock checks.");
+        const email = await prompt("  Email (Enter to skip): ");
+        if (email)
+            await claimAndMaybeVerify({ apiKey: creds.apiKey, apiBase, email, interactive: 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/login.js

@@ -1,23 +1,30 @@
-import { reissueApiKey, resendVerification, verifyEmail } from "@novence/sdk";
-import { ensureApiKey } from "../lib/auth.js";
+import { Novence } from "@novence/sdk";
+import { claimAndMaybeVerify, ensureApiKey } from "../lib/auth.js";
 import { credentialsPath, loadApiKey, resolveApiBase, saveApiKey } from "../lib/config.js";
+import { reissueApiKey, resendVerification, verifyEmail } from "@novence/sdk";
 import { flagString } from "../lib/args.js";
-import { fail, prompt, result, step } from "../lib/ui.js";
+import { fail, prompt, result, withSpin } from "../lib/ui.js";
 export async function loginCommand(args) {
     const apiBase = resolveApiBase(flagString(args.flags, "api"));
-    const email = flagString(args.flags, "email");
-    // No key yet — the normal bootstrap path handles account creation + OTP.
+    const emailFlag = flagString(args.flags, "email");
     if (!loadApiKey()) {
+        const email = emailFlag ?? (await prompt("  Email: "));
         await ensureApiKey({ apiBase, email, interactive: true });
         result(`Signed in. Key stored at ${credentialsPath()}`);
         return;
     }
-    // Key exists. Either verify this email, or recover a lost key via OTP.
-    const address = email ?? (await prompt("  Email: "));
+    const address = emailFlag ?? (await prompt("  Email: "));
     if (!address.includes("@"))
         fail(`Not a valid email: ${address}`);
-    step(`Sending a code to ${address}…`);
-    const sent = await resendVerification(address, apiBase);
+    const apiKey = loadApiKey();
+    const client = new Novence({ apiKey, baseUrl: apiBase });
+    const snap = await client.account.get();
+    if (!snap.email) {
+        await claimAndMaybeVerify({ apiKey, apiBase, email: address, interactive: true });
+        result(`${address} claimed.`);
+        return;
+    }
+    const sent = await withSpin(`Sending a code to ${address}…`, () => resendVerification(address, apiBase));
     const code = sent.verificationCode ?? (await prompt("  6-digit code from your email: "));
     if (!code)
         fail("No code entered.");

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/commands/whoami.js

@@ -8,14 +8,23 @@ export async function whoamiCommand(args) {
     if (!apiKey)
         fail("Not signed in. Run `novence login`.");
     const client = new Novence({ apiKey, baseUrl: apiBase });
+    const snap = await client.account.get();
     const quotas = await client.billing.quotas();
     // Project count is not part of the usage payload — count them directly.
     const { projects } = await client.projects.list();
     if (isJsonMode()) {
-        json({ ok: true, ...quotas, projectCount: projects.length, apiBase });
+        json({
+            ok: true,
+            ...quotas,
+            email: snap.email ?? null,
+            anonymous: !snap.email,
+            projectCount: projects.length,
+            apiBase,
+        });
         return;
     }
     result(`plan            ${quotas.plan}`);
+    result(`email           ${typeof snap.email === "string" ? snap.email : "(unclaimed)"}`);
     result(`email verified  ${quotas.emailVerified ? "yes" : "no"}`);
     result(`api             ${apiBase}`);
     result(`key             ${keySource()}`);

package/dist/index.js

@@ -2,27 +2,41 @@
 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 { claimCommand } from "./commands/claim.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 claim               Attach an email to an anonymous deploy
+    novence whoami              Plan, verification, and usage
 
   Deploy
     novence deploy              Auto-detects dist, build, out, public, _site
     novence deploy ./site       Deploy a specific directory
     --name <name>               Project name (default: "site")
     --project <id>              Redeploy an existing project
-    --email <email>             Skip the email prompt on first run
+    --email <email>             Skip the email prompt on first run (bootstrap instead of demo)
 
   Global
     --json                      Machine-readable output (implies --no-input)
@@ -56,11 +70,41 @@ 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"],
+        claim: ["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 "claim":
+            return claimCommand(args);
         case "projects":
         case "ls":
             return projectsCommand(args);
@@ -71,5 +115,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/auth.d.ts

@@ -2,16 +2,20 @@ export interface Credentials {
     apiKey: string;
     /** True when this run created the account, so callers can tailor next steps. */
     fresh: boolean;
+    anonymous: boolean;
 }
 /**
- * Returns a usable API key, bootstrapping interactively if none is stored.
- *
- * The API currently requires an email at bootstrap. Once anonymous deploys land
- * (`POST /v1/demo`), deploy should publish first and claim afterwards — see the
- * deploy-first note in the README.
+ * Returns a usable API key. With no stored key and no `--email`, creates an
+ * anonymous demo account so deploy can print a live URL first.
  */
 export declare function ensureApiKey(opts: {
     apiBase: string;
     email?: string;
     interactive: boolean;
 }): Promise<Credentials>;
+export declare function claimAndMaybeVerify(opts: {
+    apiKey: string;
+    apiBase: string;
+    email: string;
+    interactive: boolean;
+}): Promise<void>;

package/dist/lib/auth.js

@@ -1,34 +1,35 @@
-import { bootstrapAccount, verifyEmail } from "@novence/sdk";
+import { bootstrapAccount, claimAccount, createDemoAccount, verifyEmail } from "@novence/sdk";
 import { loadApiKey, saveApiKey } from "./config.js";
-import { fail, prompt, step, warn } from "./ui.js";
+import { fail, prompt, step, warn, withSpin } from "./ui.js";
 /**
- * Returns a usable API key, bootstrapping interactively if none is stored.
- *
- * The API currently requires an email at bootstrap. Once anonymous deploys land
- * (`POST /v1/demo`), deploy should publish first and claim afterwards — see the
- * deploy-first note in the README.
+ * Returns a usable API key. With no stored key and no `--email`, creates an
+ * anonymous demo account so deploy can print a live URL first.
  */
 export async function ensureApiKey(opts) {
     const existing = loadApiKey();
     if (existing)
-        return { apiKey: existing, fresh: false };
-    if (!opts.interactive) {
-        fail("No API key found. Set NOVENCE_API_KEY, or run `novence login` first.\n" +
-            "  Non-interactive runs cannot complete the email OTP step.");
-    }
-    const email = opts.email ?? (await prompt("  Email (for your account + site URL): "));
+        return { apiKey: existing, fresh: false, anonymous: false };
+    if (opts.email)
+        return bootstrapWithEmail(opts.email, opts.apiBase, opts.interactive);
+    const demo = await withSpin("Creating a temporary account…", () => createDemoAccount(opts.apiBase));
+    const path = saveApiKey(demo.apiKey);
+    step(`Anonymous account ${demo.accountId} · key saved to ${path}`);
+    warn("Unclaimed site — run `novence claim --email you@example.com` to keep it.");
+    return { apiKey: demo.apiKey, fresh: true, anonymous: true };
+}
+async function bootstrapWithEmail(email, apiBase, interactive) {
     if (!email.includes("@"))
         fail(`Not a valid email: ${email}`);
-    step(`Creating your account (${email})…`);
     let boot;
     try {
-        boot = await bootstrapAccount(email, opts.apiBase);
+        boot = await withSpin(`Creating your account (${email})…`, () => bootstrapAccount(email, apiBase));
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         if (/exists|already|409/i.test(message)) {
             fail(`${email} already has an account. Recover the key with an OTP:\n` +
-                "  novence login --email " + email);
+                "  novence login --email " +
+                email);
         }
         throw err;
     }
@@ -36,19 +37,42 @@ export async function ensureApiKey(opts) {
     step(`Account ${boot.accountId} · plan ${boot.plan}`);
     step(`Key saved to ${path}`);
     if (boot.verificationCode) {
-        // Local/dev API returns the OTP inline.
-        await verifyEmail(email, boot.verificationCode, opts.apiBase);
+        await verifyEmail(email, boot.verificationCode, apiBase);
         step("Email verified");
     }
-    else if (boot.emailVerificationRequired) {
+    else if (boot.emailVerificationRequired && interactive) {
         const code = await prompt("  6-digit code from your email (Enter to skip): ");
         if (code) {
-            await verifyEmail(email, code, opts.apiBase);
+            await verifyEmail(email, code, apiBase);
             step("Email verified");
         }
         else {
             warn("Unverified: 1 project, 3 deploys/mo, checks skipped. Run `novence login` to verify.");
         }
     }
-    return { apiKey: boot.apiKey, fresh: true };
+    else if (boot.emailVerificationRequired) {
+        warn("Unverified: run `novence login --email " + email + "` to unlock checks.");
+    }
+    return { apiKey: boot.apiKey, fresh: true, anonymous: false };
+}
+export async function claimAndMaybeVerify(opts) {
+    if (!opts.email.includes("@"))
+        fail(`Not a valid email: ${opts.email}`);
+    const claimed = await withSpin(`Claiming account for ${opts.email}…`, () => claimAccount(opts.apiKey, opts.email, opts.apiBase));
+    if (claimed.verificationCode) {
+        await verifyEmail(opts.email, claimed.verificationCode, opts.apiBase);
+        step("Email verified");
+        return;
+    }
+    if (!opts.interactive) {
+        warn("OTP emailed. Run `novence login --email " + opts.email + "` to verify.");
+        return;
+    }
+    const code = await prompt("  6-digit code from your email: ");
+    if (!code) {
+        warn("Skipped verify. Run `novence login --email " + opts.email + "` later.");
+        return;
+    }
+    await verifyEmail(opts.email, code, opts.apiBase);
+    step("Email verified");
 }

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

@@ -1,10 +1,23 @@
+export interface Spinner {
+    update(message: string): void;
+    stop(done?: string): void;
+}
 export declare function setJsonMode(on: boolean): void;
 export declare function isJsonMode(): boolean;
+export declare function isInteractive(): boolean;
 /** Progress goes to stderr so `novence deploy … > url.txt` stays clean. */
 export declare function step(message: string): void;
+/**
+ * Animate a packet-on-a-wire spinner on stderr while work runs.
+ * No-ops the animation in --json, CI, or when stderr is not a TTY.
+ */
+export declare function spin(label: string): Spinner;
+export declare function withSpin<T>(label: string, work: (spinner: Spinner) => Promise<T>, done?: string | ((value: T) => string)): Promise<T>;
 export declare function warn(message: string): void;
 /** The one line callers pipe. Always stdout. */
 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

@@ -1,18 +1,107 @@
 import { createInterface } from "node:readline/promises";
 import { stdin, stdout } from "node:process";
 let jsonMode = false;
+let cursorHidden = false;
+let activeSpinner = null;
+/** Packet traveling along a wire. Same width every frame so the line does not jump. */
+const PACKET_FRAMES = ["──·────", "───·───", "────·──", "─────·─", "──────·", "─────·─", "────·──", "───·───"];
+const PACKET_INTERVAL_MS = 100;
 export function setJsonMode(on) {
     jsonMode = on;
 }
 export function isJsonMode() {
     return jsonMode;
 }
+export function isInteractive() {
+    return Boolean(process.stderr.isTTY) && !jsonMode && !process.env.CI;
+}
+function hideCursor() {
+    if (cursorHidden || !process.stderr.isTTY)
+        return;
+    process.stderr.write("\x1b[?25l");
+    cursorHidden = true;
+}
+function showCursor() {
+    if (!cursorHidden)
+        return;
+    process.stderr.write("\x1b[?25h");
+    cursorHidden = false;
+}
+process.on("exit", showCursor);
+function stopActiveSpinner() {
+    activeSpinner?.stop();
+}
 /** Progress goes to stderr so `novence deploy … > url.txt` stays clean. */
 export function step(message) {
     if (!jsonMode)
         process.stderr.write(`  ${message}\n`);
 }
+/**
+ * Animate a packet-on-a-wire spinner on stderr while work runs.
+ * No-ops the animation in --json, CI, or when stderr is not a TTY.
+ */
+export function spin(label) {
+    stopActiveSpinner();
+    if (!isInteractive()) {
+        step(label);
+        const spinner = {
+            update() { },
+            stop(done) {
+                if (activeSpinner !== spinner)
+                    return;
+                activeSpinner = null;
+                if (done)
+                    step(done);
+            },
+        };
+        activeSpinner = spinner;
+        return spinner;
+    }
+    let i = 0;
+    let text = label;
+    let stopped = false;
+    hideCursor();
+    const draw = () => {
+        process.stderr.write(`\r  ${PACKET_FRAMES[i % PACKET_FRAMES.length]} ${text}\x1b[K`);
+        i += 1;
+    };
+    draw();
+    const id = setInterval(draw, PACKET_INTERVAL_MS);
+    const spinner = {
+        update(message) {
+            text = message;
+        },
+        stop(done) {
+            if (stopped)
+                return;
+            stopped = true;
+            clearInterval(id);
+            if (activeSpinner === spinner)
+                activeSpinner = null;
+            if (done)
+                process.stderr.write(`\r  ${done}\x1b[K\n`);
+            else
+                process.stderr.write(`\r\x1b[K`);
+            showCursor();
+        },
+    };
+    activeSpinner = spinner;
+    return spinner;
+}
+export async function withSpin(label, work, done) {
+    const spinner = spin(label);
+    try {
+        const value = await work(spinner);
+        spinner.stop(typeof done === "function" ? done(value) : done);
+        return value;
+    }
+    catch (err) {
+        spinner.stop();
+        throw err;
+    }
+}
 export function warn(message) {
+    stopActiveSpinner();
     process.stderr.write(`  ! ${message}\n`);
 }
 /** The one line callers pipe. Always stdout. */
@@ -23,6 +112,7 @@ export function json(value) {
     stdout.write(JSON.stringify(value, null, 2) + "\n");
 }
 export function fail(message) {
+    stopActiveSpinner();
     if (jsonMode) {
         stdout.write(JSON.stringify({ ok: false, error: message }, null, 2) + "\n");
     }
@@ -32,6 +122,7 @@ export function fail(message) {
     process.exit(1);
 }
 export async function prompt(question) {
+    stopActiveSpinner();
     if (!stdin.isTTY) {
         fail(`Cannot prompt for "${question.trim()}" — stdin is not a TTY. Pass the value as a flag.`);
     }
@@ -46,3 +137,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,7 +1,7 @@
 {
   "name": "novence",
-  "version": "0.0.2",
-  "description": "CLI for Novence \u2014 deploy a static site to the edge in one command.",
+  "version": "0.1.1",
+  "description": "CLI for Novence — deploy a static site to the edge in one command.",
   "license": "MIT",
   "type": "module",
   "bin": {
@@ -17,7 +17,7 @@
   "engines": {
     "node": ">=18"
   },
-  "homepage": "https://novence.ai/docs",
+  "homepage": "https://novence.ai/cli",
   "bugs": {
     "url": "https://novence.ai/support"
   },
@@ -29,21 +29,25 @@
     "hosting",
     "edge",
     "static-site",
-    "ai-agents"
+    "ai-agents",
+    "claude",
+    "cursor",
+    "mcp-server",
+    "static-hosting",
+    "netlify-alternative"
   ],
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "prepublishOnly": "pnpm run build"
-  },
   "dependencies": {
-    "@novence/sdk": "^0.2.0"
+    "@novence/sdk": "^0.2.3"
   },
   "devDependencies": {
     "@types/node": "^22.10.2",
     "typescript": "^5.7.2"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
   }
-}
+}