novence 0.1.0 → 0.1.2

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
 
@@ -26,10 +34,21 @@ Requires Node 18+.
 ```bash
 novence deploy              # auto-detects dist, build, out, public, _site
 novence deploy ./site       # or point at a directory
+novence deploy report.html  # one HTML file (dashboard, report, artifact)
 ```
 
-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 +62,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`) |
@@ -59,6 +78,7 @@ 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
 ```
 
@@ -66,7 +86,19 @@ 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
+## 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:
 
@@ -82,7 +114,7 @@ default name.
 }
 ```
 
-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.
@@ -91,17 +123,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/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,46 +1,73 @@
-import { existsSync, statSync } from "node:fs";
-import { resolve } from "node:path";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { basename, 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, siteUrl, 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));
 /** Common build output directories, checked in order when no dir is given. */
 const CANDIDATE_DIRS = ["dist", "build", "out", "public", "_site"];
-function resolveSiteDir(explicit) {
+function resolveSiteSource(explicit) {
     if (explicit) {
-        const dir = resolve(explicit);
-        if (!existsSync(dir) || !statSync(dir).isDirectory())
-            fail(`Not a directory: ${dir}`);
-        return dir;
+        const target = resolve(explicit);
+        if (!existsSync(target))
+            fail(`Not found: ${target}`);
+        const st = statSync(target);
+        if (st.isFile()) {
+            if (!target.toLowerCase().endsWith(".html")) {
+                fail(`Not a directory or .html file: ${target}`);
+            }
+            return { kind: "html", path: target };
+        }
+        if (!st.isDirectory())
+            fail(`Not a directory: ${target}`);
+        return { kind: "dir", path: target };
     }
     for (const candidate of CANDIDATE_DIRS) {
         const dir = resolve(process.cwd(), candidate);
         if (existsSync(dir) && statSync(dir).isDirectory())
-            return dir;
+            return { kind: "dir", path: dir };
     }
     return fail(`No build output found. Looked for ${CANDIDATE_DIRS.join(", ")} in ${process.cwd()}.\n` +
-        "  Pass one explicitly:  novence deploy ./your-dir");
+        "  Pass a directory or an HTML file:  novence deploy ./your-dir   or   novence deploy report.html");
 }
-async function waitForLive(client, projectId) {
+async function waitUntilLive(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 {
+        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.");
 }
+async function publish(client, projectId) {
+    await client.deployments.create(projectId);
+    return waitUntilLive(client, projectId);
+}
 function reportChecks(deployment) {
     const checks = deployment.checksResults;
     if (!checks)
@@ -57,44 +84,66 @@ function reportChecks(deployment) {
 }
 export async function deployCommand(args) {
     const apiBase = resolveApiBase(flagString(args.flags, "api"));
-    const siteDir = resolveSiteDir(args.positionals[0]);
-    if (!existsSync(resolve(siteDir, "index.html"))) {
-        fail(`${siteDir} has no index.html — a static site needs one at its root.`);
+    const source = resolveSiteSource(args.positionals[0]);
+    if (source.kind === "dir" && !existsSync(resolve(source.path, "index.html"))) {
+        fail(`${source.path} has no index.html — a static site needs one at its root.`);
     }
     let projectId = flagString(args.flags, "project");
     try {
-        await runDeploy(args, apiBase, siteDir);
+        await runDeploy(args, apiBase, source);
     }
     catch (err) {
         fail(explain(err, { apiBase, projectId }));
     }
 }
-async function runDeploy(args, apiBase, siteDir) {
-    const { apiKey } = await ensureApiKey({
+async function runDeploy(args, apiBase, source) {
+    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 projectUrl;
-    if (projectId) {
-        const { project } = await client.projects.get(projectId);
-        projectUrl = project.url;
-        step(`Reusing project ${project.name} (${project.suffix})`);
+    let fileCount = 1;
+    let deployment;
+    if (source.kind === "html") {
+        const html = readFileSync(source.path, "utf8");
+        const defaultName = basename(source.path).replace(/\.html?$/i, "") || "artifact";
+        const name = flagString(args.flags, "name") ?? defaultName;
+        const published = await withSpin(`Publishing ${source.path}…`, () => client.publishHtml({
+            html,
+            title: name,
+            projectId,
+        }), (result) => (result.created ? "Created project" : "Updated project"));
+        projectId = published.projectId;
+        projectUrl = published.url;
+        if (!projectId)
+            fail("Missing project id");
+        const htmlProjectId = projectId;
+        deployment = await waitUntilLive(client, htmlProjectId);
     }
     else {
-        const name = flagString(args.flags, "name") ?? "site";
-        const created = await client.projects.create({ name });
-        projectId = created.project.id;
-        projectUrl = created.url;
-        step(`Created project ${name} (${created.project.suffix})`);
+        if (projectId) {
+            const { project } = await client.projects.get(projectId);
+            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;
+            projectUrl = created.url;
+            step(`Created project ${name} (${created.project.suffix})`);
+        }
+        if (!projectId)
+            fail("Missing project id");
+        const dirProjectId = projectId;
+        const { uploaded } = await withSpin(`Uploading ${source.path}…`, () => client.files.uploadDir(dirProjectId, source.path), ({ uploaded: files }) => `Uploaded ${files.length} file${files.length === 1 ? "" : "s"}`);
+        fileCount = uploaded.length;
+        deployment = await publish(client, dirProjectId);
     }
-    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);
     if (deployment.status === "failed") {
         if (isJsonMode()) {
             json({ ok: false, projectId, status: deployment.status, error: deployment.errorMessage });
@@ -104,6 +153,8 @@ async function runDeploy(args, apiBase, siteDir) {
     }
     reportChecks(deployment);
     const liveUrl = siteUrl(deployment.liveUrl ?? projectUrl);
+    const previewUrl = deployment.previewUrl ? siteUrl(deployment.previewUrl) : null;
+    const distinctPreview = previewUrl && previewUrl !== liveUrl ? previewUrl : null;
     if (isJsonMode()) {
         json({
             ok: true,
@@ -111,11 +162,20 @@ async function runDeploy(args, apiBase, siteDir) {
             deploymentId: deployment.id,
             status: deployment.status,
             url: liveUrl,
-            files: uploaded.length,
+            ...(distinctPreview ? { previewUrl: distinctPreview } : {}),
+            files: fileCount,
             checks: deployment.checksResults ?? null,
         });
         return;
     }
+    if (distinctPreview)
+        step(`Preview  ${distinctPreview}`);
     // 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/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/rollback.d.ts

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

package/dist/commands/rollback.js

@@ -0,0 +1,46 @@
+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";
+export async function rollbackCommand(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 = flagString(args.flags, "project") ?? args.positionals[0];
+    const deploymentId = flagString(args.flags, "deployment");
+    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.rollback(projectId, {
+            ...(deploymentId ? { deploymentId } : {}),
+        });
+        const liveUrl = siteUrl(deployment.liveUrl ?? deployment.previewUrl ?? "");
+        const previewUrl = deployment.previewUrl ? siteUrl(deployment.previewUrl) : null;
+        if (isJsonMode()) {
+            json({
+                ok: true,
+                projectId,
+                deploymentId: deployment.id,
+                status: deployment.status,
+                url: liveUrl,
+                ...(previewUrl && previewUrl !== liveUrl ? { previewUrl } : {}),
+            });
+            return;
+        }
+        step("Restored previous snapshot (HTML cache ~60s; hard-refresh if the old page lingers).");
+        if (previewUrl && previewUrl !== liveUrl)
+            step(`Preview  ${previewUrl}`);
+        result(liveUrl);
+    }
+    catch (err) {
+        fail(explain(err, { apiBase, projectId: wanted }));
+    }
+}

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

@@ -8,17 +8,20 @@ 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";
+import { rollbackCommand } from "./commands/rollback.js";
 const HELP = `
   novence — deploy a static site to the edge
 
   Usage
-    novence deploy [dir]        Upload a directory and publish it live
+    novence deploy [dir|file]   Upload a directory or one .html file and publish it live
+    novence rollback            Restore the previous live snapshot (Pro/Scale)
     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)
@@ -27,14 +30,21 @@ const HELP = `
     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 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
+    novence deploy report.html  Publish a single HTML file as the site
     --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)
+
+  Rollback (Pro/Scale)
+    novence rollback            Restore the previous live snapshot
+    --project <id>              Project (default: first in the list)
+    --deployment <id>           Specific retained deploy (last 5)
 
   Global
     --json                      Machine-readable output (implies --no-input)
@@ -72,6 +82,7 @@ async function main() {
     // change behaviour.
     const ALLOWED = {
         deploy: ["name", "project", "email"],
+        claim: ["email"],
         open: [],
         checks: [],
         domains: ["project", "primary", "redirect"],
@@ -80,6 +91,7 @@ async function main() {
         ls: [],
         login: ["email", "recover"],
         whoami: [],
+        rollback: ["project", "deployment"],
     };
     const allowed = ALLOWED[args.command];
     if (allowed) {
@@ -100,11 +112,15 @@ async function main() {
             return keysCommand(args);
         case "login":
             return loginCommand(args);
+        case "claim":
+            return claimCommand(args);
         case "projects":
         case "ls":
             return projectsCommand(args);
         case "whoami":
             return whoamiCommand(args);
+        case "rollback":
+            return rollbackCommand(args);
         default:
             fail(`Unknown command: ${args.command}\n  Run \`novence --help\` for usage.`);
     }

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

@@ -1,7 +1,18 @@
+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;

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.`);
     }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "novence",
-  "version": "0.1.0",
-  "description": "CLI for Novence \u2014 deploy a static site to the edge in one command.",
+  "version": "0.1.2",
+  "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.2"
+    "@novence/sdk": "^0.2.4"
   },
   "devDependencies": {
     "@types/node": "^22.10.2",
     "typescript": "^5.7.2"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
   }
-}
+}