nerdsystem 0.0.22 → 0.0.23

package/dist/cli.js

@@ -67,7 +67,7 @@ const HELP = `nerd: start, check, and deploy a web app on nerdsystem
   nerd billing portal                 Manage cards, invoices, and plan
   nerd members [invite <email> --role r | remove <userId>]   Org members and invitations
   nerd clients [create <slug> --name n | release <slug>]     Studio: one org per client, billed through yours
-  nerd domains [add <hostname> | remove <id>]                Custom domains for this project
+  nerd domains [add <domain> | remove <id>]                  The app on your own domain, with the DNS steps for it
   nerd logs [--since 30m] [--limit 100] [--q text] [--pr n]  Logs from the deployed app
   nerd audit [--out file.csv]         Export deployments and builds (Studio)
 

package/dist/commands/init.js

@@ -192,4 +192,4 @@ export async function init(dir, args) {
     log.ok(`Ready. Next:\n  cd ${dir}\n  pnpm install\n  nerd dev\n\nThen open the folder in your coding agent and ask it to build the first feature; the nerdsystem skill walks it through.\nDeploys go to ${project.url}`);
 }
 // Kept in sync with packages/sdk/package.json by the release script.
-const SDK_VERSION = "0.0.22";
+const SDK_VERSION = "0.0.23";

package/dist/commands/org.d.ts

@@ -11,6 +11,23 @@ export declare function membersRemove(userId: string | undefined, opts: {
     json: boolean;
     org?: string;
 }): Promise<void>;
+/** The platform's steps for the company that runs the domain's DNS. Absent from an older platform. */
+interface DomainSetup {
+    address: string;
+    forwards: string | null;
+    dnsHost: {
+        id: string;
+        name: string;
+    };
+    method: string;
+    steps: string[];
+    after: string;
+}
+/**
+ * The steps as the platform wrote them, numbered, with a line telling an agent how to pass them on. The person
+ * who owns the domain is usually not technical: they get these steps and nothing to choose between.
+ */
+export declare function setupText(s: DomainSetup): string;
 export declare function domainsList(opts: {
     json: boolean;
 }): Promise<void>;
@@ -45,3 +62,4 @@ export declare function clientsRelease(slug: string | undefined, opts: {
     json: boolean;
     org?: string;
 }): Promise<void>;
+export {};

package/dist/commands/org.js

@@ -35,23 +35,46 @@ export async function membersRemove(userId, opts) {
         return printJson(r);
     log.ok("Removed.");
 }
+/**
+ * The steps as the platform wrote them, numbered, with a line telling an agent how to pass them on. The person
+ * who owns the domain is usually not technical: they get these steps and nothing to choose between.
+ */
+export function setupText(s) {
+    const known = s.dnsHost.id !== "unknown";
+    return [
+        `The app's address will be https://${s.address}${s.forwards ? `, and ${s.forwards} forwards to it` : ""}.`,
+        known ? `This domain's DNS is run by ${s.dnsHost.name}${s.method === "move-dns" ? ", which cannot point a bare domain name at another service, so the DNS moves to Cloudflare (free) first" : ""}. The steps for the domain's owner:` : "The steps for the domain's owner:",
+        "",
+        ...s.steps.map((step, i) => `  ${i + 1}. ${step}`),
+        "",
+        s.after,
+        "",
+        "If you are a coding agent: give the owner these steps as they are, numbered, and nothing else to decide. Do not ask which company they use (it was looked up) and do not offer other record types. When they say it is done, run `nerd domains` until the status is active, then open the address to confirm.",
+    ].join("\n");
+}
 export async function domainsList(opts) {
     const nerd = readNerdJson(findProjectRoot());
     const r = await ApiClient.fromConfig().get(projectPath(nerd, "/domains"));
     if (opts.json)
         return printJson(r);
     if (!r.domains.length)
-        return log.info(`No custom domains. Add one: nerd domains add app.example.com`);
-    table(r.domains.map((d) => ({ hostname: d.hostname, status: d.status, ssl: d.sslStatus ?? "", error: d.lastError ?? "", id: d.id })), ["hostname", "status", "ssl", "error", "id"]);
-    log.info(`\nPoint each hostname at ${r.cnameTarget} with a CNAME record.`);
+        return log.info(`No custom domains. Add one: nerd domains add example.com`);
+    table(r.domains.map((d) => ({ hostname: d.hostname, status: d.status, ssl: d.sslStatus ?? "", does: d.redirectTo ? `forwards to ${d.redirectTo}` : "the app", error: d.lastError ?? "", id: d.id })), ["hostname", "status", "ssl", "does", "error", "id"]);
+    // Only addresses still waiting for their DNS records have steps left to do.
+    for (const s of r.setups ?? [])
+        log.info(`\n${setupText(s)}`);
+    if (!r.setups && r.domains.some((d) => d.status !== "active"))
+        log.info(`\nPoint each hostname at ${r.cnameTarget} with a CNAME record.`);
 }
 export async function domainsAdd(hostname, opts) {
     if (!hostname)
-        throw new CliError("Usage: nerd domains add app.example.com");
+        throw new CliError("Usage: nerd domains add example.com");
     const nerd = readNerdJson(findProjectRoot());
     const r = await ApiClient.fromConfig().post(projectPath(nerd, "/domains"), { hostname });
     if (opts.json)
         return printJson(r);
+    if (r.setup)
+        return log.ok(`Added ${r.domain.hostname}.\n\n${setupText(r.setup)}`);
     log.ok(`Added ${r.domain.hostname}. Create this DNS record, then check with \`nerd domains\`:\n\n  ${r.domain.hostname}  CNAME  ${r.cnameTarget}`);
 }
 export async function domainsRemove(idOrHostname, opts) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nerdsystem",
-  "version": "0.0.22",
+  "version": "0.0.23",
   "description": "nerd: start, check, and deploy a web app on nerdsystem from the terminal or a coding agent.",
   "type": "module",
   "bin": {

package/template/.claude/skills/nerdsystem/SKILL.md

@@ -178,6 +178,17 @@ After a deploy is live, `nerd deploy` asks the platform for a model review of th
 - **Secrets** (Stripe keys, API tokens): never in code or in the client. Locally they live in `.dev.vars` (gitignored). For production, ask the person to add it under the app's Settings tab in the dashboard, or to run `nerd secret set NAME` and paste the value; it reaches the app as `c.env.NAME` on the next deploy. Pull request previews do not get it unless it was set with `--previews` (use that only for keys that are safe in a preview, such as a test-mode key). `nerd secret list` shows names only. Do not put a real secret value in any command you run yourself.
 - **Email**: `sendEmail(c.env, { to, subject, text, html?, replyTo? })` from `@nerdsystem/sdk` sends through the platform. The relay only sends to addresses that have an account on this app (someone who signed up); any other recipient is refused with a 400, and the sender name is always the app's name. On the Free plan the recipient must also have confirmed their address by finishing a password reset (403 otherwise); paid plans can write to every signed-up user. It is limited per day by plan (50 on Free, 1,000 on Pro at $39 a month, 2,000 on Studio at $99 a month), so use it for transactional mail such as receipts and notifications, not bulk. Plans can be paid monthly or yearly at ten times the monthly price. Pass `replyTo` (the owner's address, or one they give you) whenever a person might answer the message; without it replies go to a mailbox nobody reads. Mail goes out under the app's name from the platform's address; on Pro and Studio the owner can switch it to their own domain in the dashboard under Settings, which needs no code change.
 
+## Putting the app on the owner's own domain
+
+Paid plans only; on Free the command answers with the plan that includes it, so say that and stop.
+
+1. Run `nerd domains add example.com` with the bare domain the owner gives you. The platform makes `www.example.com` the app's address and sets the bare name up to forward to it. It also looks up which company runs the domain's DNS and prints the exact steps for that company.
+2. Give the owner those steps as printed, numbered. Do not ask who their registrar is, do not show a table of record types, and do not offer alternatives: the platform already chose. The steps are things only they can do (signing in where the domain is managed).
+3. When they say it is done, run `nerd domains` every minute or two until the status is `active`, then open the address and confirm it loads with https. If it is still pending after an hour, run `nerd domains` and read the steps again with them; the usual cause is a leftover parking record.
+4. Tell them two things once it is live: they sign in once more on the new address (same account, same data), and links to the old `.nerdsystem.app` address keep working.
+
+For a subdomain such as `app.example.com`, the same command gives a single record to add.
+
 ## Debugging production
 
 When something is wrong on the deployed app: `nerd logs --since 1h` (add `--q "text"` to search, `--pr 12` for a preview) shows errors with the request that caused them. Reproduce locally with `nerd dev` using the same input, fix it, run `nerd verify`, and deploy or open a pull request. If a deploy made things worse, `nerd rollback` puts the previous production bundle back without touching the database. Write a one-line note on every deploy (`nerd deploy --note "fix: todos query filtered by user"`); the dashboard shows these as a changelog people can read.

package/template/.cursor/rules/nerdsystem.mdc

@@ -2,7 +2,7 @@
 description: How to build, run, and deploy this app on nerdsystem. Applies to server, database, auth, and deploy work.
 alwaysApply: true
 ---
-<!-- generated from .claude/skills/nerdsystem/SKILL.md (7bfa9a6cabd1); edit the skill, then run: nerd agents sync -->
+<!-- generated from .claude/skills/nerdsystem/SKILL.md (1794b8a1a530); edit the skill, then run: nerd agents sync -->
 
 # Building on nerdsystem
 
@@ -179,6 +179,17 @@ After a deploy is live, `nerd deploy` asks the platform for a model review of th
 - **Secrets** (Stripe keys, API tokens): never in code or in the client. Locally they live in `.dev.vars` (gitignored). For production, ask the person to add it under the app's Settings tab in the dashboard, or to run `nerd secret set NAME` and paste the value; it reaches the app as `c.env.NAME` on the next deploy. Pull request previews do not get it unless it was set with `--previews` (use that only for keys that are safe in a preview, such as a test-mode key). `nerd secret list` shows names only. Do not put a real secret value in any command you run yourself.
 - **Email**: `sendEmail(c.env, { to, subject, text, html?, replyTo? })` from `@nerdsystem/sdk` sends through the platform. The relay only sends to addresses that have an account on this app (someone who signed up); any other recipient is refused with a 400, and the sender name is always the app's name. On the Free plan the recipient must also have confirmed their address by finishing a password reset (403 otherwise); paid plans can write to every signed-up user. It is limited per day by plan (50 on Free, 1,000 on Pro at $39 a month, 2,000 on Studio at $99 a month), so use it for transactional mail such as receipts and notifications, not bulk. Plans can be paid monthly or yearly at ten times the monthly price. Pass `replyTo` (the owner's address, or one they give you) whenever a person might answer the message; without it replies go to a mailbox nobody reads. Mail goes out under the app's name from the platform's address; on Pro and Studio the owner can switch it to their own domain in the dashboard under Settings, which needs no code change.
 
+## Putting the app on the owner's own domain
+
+Paid plans only; on Free the command answers with the plan that includes it, so say that and stop.
+
+1. Run `nerd domains add example.com` with the bare domain the owner gives you. The platform makes `www.example.com` the app's address and sets the bare name up to forward to it. It also looks up which company runs the domain's DNS and prints the exact steps for that company.
+2. Give the owner those steps as printed, numbered. Do not ask who their registrar is, do not show a table of record types, and do not offer alternatives: the platform already chose. The steps are things only they can do (signing in where the domain is managed).
+3. When they say it is done, run `nerd domains` every minute or two until the status is `active`, then open the address and confirm it loads with https. If it is still pending after an hour, run `nerd domains` and read the steps again with them; the usual cause is a leftover parking record.
+4. Tell them two things once it is live: they sign in once more on the new address (same account, same data), and links to the old `.nerdsystem.app` address keep working.
+
+For a subdomain such as `app.example.com`, the same command gives a single record to add.
+
 ## Debugging production
 
 When something is wrong on the deployed app: `nerd logs --since 1h` (add `--q "text"` to search, `--pr 12` for a preview) shows errors with the request that caused them. Reproduce locally with `nerd dev` using the same input, fix it, run `nerd verify`, and deploy or open a pull request. If a deploy made things worse, `nerd rollback` puts the previous production bundle back without touching the database. Write a one-line note on every deploy (`nerd deploy --note "fix: todos query filtered by user"`); the dashboard shows these as a changelog people can read.

package/template/.github/copilot-instructions.md

@@ -1,4 +1,4 @@
-<!-- generated from .claude/skills/nerdsystem/SKILL.md (7bfa9a6cabd1); edit the skill, then run: nerd agents sync -->
+<!-- generated from .claude/skills/nerdsystem/SKILL.md (1794b8a1a530); edit the skill, then run: nerd agents sync -->
 
 # Building on nerdsystem
 
@@ -175,6 +175,17 @@ After a deploy is live, `nerd deploy` asks the platform for a model review of th
 - **Secrets** (Stripe keys, API tokens): never in code or in the client. Locally they live in `.dev.vars` (gitignored). For production, ask the person to add it under the app's Settings tab in the dashboard, or to run `nerd secret set NAME` and paste the value; it reaches the app as `c.env.NAME` on the next deploy. Pull request previews do not get it unless it was set with `--previews` (use that only for keys that are safe in a preview, such as a test-mode key). `nerd secret list` shows names only. Do not put a real secret value in any command you run yourself.
 - **Email**: `sendEmail(c.env, { to, subject, text, html?, replyTo? })` from `@nerdsystem/sdk` sends through the platform. The relay only sends to addresses that have an account on this app (someone who signed up); any other recipient is refused with a 400, and the sender name is always the app's name. On the Free plan the recipient must also have confirmed their address by finishing a password reset (403 otherwise); paid plans can write to every signed-up user. It is limited per day by plan (50 on Free, 1,000 on Pro at $39 a month, 2,000 on Studio at $99 a month), so use it for transactional mail such as receipts and notifications, not bulk. Plans can be paid monthly or yearly at ten times the monthly price. Pass `replyTo` (the owner's address, or one they give you) whenever a person might answer the message; without it replies go to a mailbox nobody reads. Mail goes out under the app's name from the platform's address; on Pro and Studio the owner can switch it to their own domain in the dashboard under Settings, which needs no code change.
 
+## Putting the app on the owner's own domain
+
+Paid plans only; on Free the command answers with the plan that includes it, so say that and stop.
+
+1. Run `nerd domains add example.com` with the bare domain the owner gives you. The platform makes `www.example.com` the app's address and sets the bare name up to forward to it. It also looks up which company runs the domain's DNS and prints the exact steps for that company.
+2. Give the owner those steps as printed, numbered. Do not ask who their registrar is, do not show a table of record types, and do not offer alternatives: the platform already chose. The steps are things only they can do (signing in where the domain is managed).
+3. When they say it is done, run `nerd domains` every minute or two until the status is `active`, then open the address and confirm it loads with https. If it is still pending after an hour, run `nerd domains` and read the steps again with them; the usual cause is a leftover parking record.
+4. Tell them two things once it is live: they sign in once more on the new address (same account, same data), and links to the old `.nerdsystem.app` address keep working.
+
+For a subdomain such as `app.example.com`, the same command gives a single record to add.
+
 ## Debugging production
 
 When something is wrong on the deployed app: `nerd logs --since 1h` (add `--q "text"` to search, `--pr 12` for a preview) shows errors with the request that caused them. Reproduce locally with `nerd dev` using the same input, fix it, run `nerd verify`, and deploy or open a pull request. If a deploy made things worse, `nerd rollback` puts the previous production bundle back without touching the database. Write a one-line note on every deploy (`nerd deploy --note "fix: todos query filtered by user"`); the dashboard shows these as a changelog people can read.

package/template/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- generated from .claude/skills/nerdsystem/SKILL.md (7bfa9a6cabd1); edit the skill, then run: nerd agents sync -->
+<!-- generated from .claude/skills/nerdsystem/SKILL.md (1794b8a1a530); edit the skill, then run: nerd agents sync -->
 
 # Building on nerdsystem
 
@@ -175,6 +175,17 @@ After a deploy is live, `nerd deploy` asks the platform for a model review of th
 - **Secrets** (Stripe keys, API tokens): never in code or in the client. Locally they live in `.dev.vars` (gitignored). For production, ask the person to add it under the app's Settings tab in the dashboard, or to run `nerd secret set NAME` and paste the value; it reaches the app as `c.env.NAME` on the next deploy. Pull request previews do not get it unless it was set with `--previews` (use that only for keys that are safe in a preview, such as a test-mode key). `nerd secret list` shows names only. Do not put a real secret value in any command you run yourself.
 - **Email**: `sendEmail(c.env, { to, subject, text, html?, replyTo? })` from `@nerdsystem/sdk` sends through the platform. The relay only sends to addresses that have an account on this app (someone who signed up); any other recipient is refused with a 400, and the sender name is always the app's name. On the Free plan the recipient must also have confirmed their address by finishing a password reset (403 otherwise); paid plans can write to every signed-up user. It is limited per day by plan (50 on Free, 1,000 on Pro at $39 a month, 2,000 on Studio at $99 a month), so use it for transactional mail such as receipts and notifications, not bulk. Plans can be paid monthly or yearly at ten times the monthly price. Pass `replyTo` (the owner's address, or one they give you) whenever a person might answer the message; without it replies go to a mailbox nobody reads. Mail goes out under the app's name from the platform's address; on Pro and Studio the owner can switch it to their own domain in the dashboard under Settings, which needs no code change.
 
+## Putting the app on the owner's own domain
+
+Paid plans only; on Free the command answers with the plan that includes it, so say that and stop.
+
+1. Run `nerd domains add example.com` with the bare domain the owner gives you. The platform makes `www.example.com` the app's address and sets the bare name up to forward to it. It also looks up which company runs the domain's DNS and prints the exact steps for that company.
+2. Give the owner those steps as printed, numbered. Do not ask who their registrar is, do not show a table of record types, and do not offer alternatives: the platform already chose. The steps are things only they can do (signing in where the domain is managed).
+3. When they say it is done, run `nerd domains` every minute or two until the status is `active`, then open the address and confirm it loads with https. If it is still pending after an hour, run `nerd domains` and read the steps again with them; the usual cause is a leftover parking record.
+4. Tell them two things once it is live: they sign in once more on the new address (same account, same data), and links to the old `.nerdsystem.app` address keep working.
+
+For a subdomain such as `app.example.com`, the same command gives a single record to add.
+
 ## Debugging production
 
 When something is wrong on the deployed app: `nerd logs --since 1h` (add `--q "text"` to search, `--pr 12` for a preview) shows errors with the request that caused them. Reproduce locally with `nerd dev` using the same input, fix it, run `nerd verify`, and deploy or open a pull request. If a deploy made things worse, `nerd rollback` puts the previous production bundle back without touching the database. Write a one-line note on every deploy (`nerd deploy --note "fix: todos query filtered by user"`); the dashboard shows these as a changelog people can read.

package/template/GEMINI.md

@@ -1,4 +1,4 @@
-<!-- generated from .claude/skills/nerdsystem/SKILL.md (7bfa9a6cabd1); edit the skill, then run: nerd agents sync -->
+<!-- generated from .claude/skills/nerdsystem/SKILL.md (1794b8a1a530); edit the skill, then run: nerd agents sync -->
 
 # Building on nerdsystem
 
@@ -175,6 +175,17 @@ After a deploy is live, `nerd deploy` asks the platform for a model review of th
 - **Secrets** (Stripe keys, API tokens): never in code or in the client. Locally they live in `.dev.vars` (gitignored). For production, ask the person to add it under the app's Settings tab in the dashboard, or to run `nerd secret set NAME` and paste the value; it reaches the app as `c.env.NAME` on the next deploy. Pull request previews do not get it unless it was set with `--previews` (use that only for keys that are safe in a preview, such as a test-mode key). `nerd secret list` shows names only. Do not put a real secret value in any command you run yourself.
 - **Email**: `sendEmail(c.env, { to, subject, text, html?, replyTo? })` from `@nerdsystem/sdk` sends through the platform. The relay only sends to addresses that have an account on this app (someone who signed up); any other recipient is refused with a 400, and the sender name is always the app's name. On the Free plan the recipient must also have confirmed their address by finishing a password reset (403 otherwise); paid plans can write to every signed-up user. It is limited per day by plan (50 on Free, 1,000 on Pro at $39 a month, 2,000 on Studio at $99 a month), so use it for transactional mail such as receipts and notifications, not bulk. Plans can be paid monthly or yearly at ten times the monthly price. Pass `replyTo` (the owner's address, or one they give you) whenever a person might answer the message; without it replies go to a mailbox nobody reads. Mail goes out under the app's name from the platform's address; on Pro and Studio the owner can switch it to their own domain in the dashboard under Settings, which needs no code change.
 
+## Putting the app on the owner's own domain
+
+Paid plans only; on Free the command answers with the plan that includes it, so say that and stop.
+
+1. Run `nerd domains add example.com` with the bare domain the owner gives you. The platform makes `www.example.com` the app's address and sets the bare name up to forward to it. It also looks up which company runs the domain's DNS and prints the exact steps for that company.
+2. Give the owner those steps as printed, numbered. Do not ask who their registrar is, do not show a table of record types, and do not offer alternatives: the platform already chose. The steps are things only they can do (signing in where the domain is managed).
+3. When they say it is done, run `nerd domains` every minute or two until the status is `active`, then open the address and confirm it loads with https. If it is still pending after an hour, run `nerd domains` and read the steps again with them; the usual cause is a leftover parking record.
+4. Tell them two things once it is live: they sign in once more on the new address (same account, same data), and links to the old `.nerdsystem.app` address keep working.
+
+For a subdomain such as `app.example.com`, the same command gives a single record to add.
+
 ## Debugging production
 
 When something is wrong on the deployed app: `nerd logs --since 1h` (add `--q "text"` to search, `--pr 12` for a preview) shows errors with the request that caused them. Reproduce locally with `nerd dev` using the same input, fix it, run `nerd verify`, and deploy or open a pull request. If a deploy made things worse, `nerd rollback` puts the previous production bundle back without touching the database. Write a one-line note on every deploy (`nerd deploy --note "fix: todos query filtered by user"`); the dashboard shows these as a changelog people can read.