@hasna/shortlinks 0.1.1 → 0.1.3

package/README.md

@@ -67,6 +67,17 @@ shortlinks serve --port 8787
 shortlinks doctor
 ```
 
+## Local Domain Setup
+
+Record a local mapping with the `machines` CLI and print the remaining hosts/proxy setup:
+
+```bash
+shortlinks local setup has.na --port 8787
+shortlinks local plan has.na --port 8787
+```
+
+The command emits the `/etc/hosts` line, a Caddy reverse-proxy snippet, and certificate paths. Writing `/etc/hosts` still requires sudo on macOS.
+
 ## Custom Domains
 
 Add as many domains as you need:
@@ -96,7 +107,7 @@ shortlinks cloudflare worker \
   --origin https://shortlinks.hasna.xyz
 ```
 
-Upsert DNS when `CLOUDFLARE_API_TOKEN` is available:
+Upsert DNS when `CLOUDFLARE_API_TOKEN` is available. Global API key auth is also supported with `CLOUDFLARE_API_KEY` plus `CLOUDFLARE_EMAIL`.
 
 ```bash
 shortlinks cloudflare dns has.na --target shortlinks.hasna.xyz

package/dist/cli/index.js

@@ -2560,9 +2560,9 @@ var source_default = chalk;
 
 // src/cli/index.ts
 import { existsSync as existsSync3, readFileSync as readFileSync3 } from "fs";
-import { dirname as dirname3, join as join4 } from "path";
+import { dirname as dirname3, join as join5 } from "path";
 import { fileURLToPath } from "url";
-import { spawnSync as spawnSync2 } from "child_process";
+import { spawnSync as spawnSync3 } from "child_process";
 
 // src/store.ts
 import { createHash } from "crypto";
@@ -3224,11 +3224,25 @@ SHORTLINKS_ORIGIN = "${options.origin || "https://shortlinks.example.com"}"
 `);
   return { workerPath, wranglerPath };
 }
+function cloudflareAuthHeaders(token) {
+  const apiToken = token || process.env.CLOUDFLARE_API_TOKEN;
+  if (apiToken)
+    return { authorization: `Bearer ${apiToken}` };
+  const apiKey = process.env.CLOUDFLARE_API_KEY;
+  const email = process.env.CLOUDFLARE_EMAIL;
+  if (apiKey && email) {
+    return {
+      "x-auth-key": apiKey,
+      "x-auth-email": email
+    };
+  }
+  throw new Error("Cloudflare auth is required: set CLOUDFLARE_API_TOKEN, or CLOUDFLARE_API_KEY plus CLOUDFLARE_EMAIL.");
+}
 async function cloudflareRequest(token, path, init = {}) {
   const response = await fetch(`https://api.cloudflare.com/client/v4${path}`, {
     ...init,
     headers: {
-      authorization: `Bearer ${token}`,
+      ...cloudflareAuthHeaders(token),
       "content-type": "application/json",
       ...init.headers || {}
     }
@@ -3266,8 +3280,6 @@ async function upsertCloudflareDnsRecord(options) {
   });
   if (options.dryRun)
     return plan;
-  if (!token)
-    throw new Error("CLOUDFLARE_API_TOKEN is required unless --dry-run is used.");
   const zoneId = options.zoneId || await findCloudflareZoneId(plan.hostname, token);
   const existing = await cloudflareRequest(token, `/zones/${zoneId}/dns_records?type=CNAME&name=${encodeURIComponent(plan.hostname)}`);
   const payload = JSON.stringify(plan.dnsRecord);
@@ -3312,6 +3324,54 @@ function runDomains(action, domain, options = {}) {
   };
 }
 
+// src/local.ts
+import { spawnSync as spawnSync2 } from "child_process";
+import { homedir as homedir2 } from "os";
+import { join as join4 } from "path";
+function createLocalSetupPlan(input) {
+  const domain = normalizeHostname(input.domain);
+  const targetHost = input.targetHost || "127.0.0.1";
+  const port = input.port || 8787;
+  const certDir = input.certDir || join4(homedir2(), ".hasna", "machines", "certs");
+  const certPath = join4(certDir, `${domain}.pem`);
+  const keyPath = join4(certDir, `${domain}-key.pem`);
+  return {
+    domain,
+    targetHost,
+    port,
+    hostsEntry: `${targetHost} ${domain}`,
+    caddySnippet: `${domain} {
+  reverse_proxy ${targetHost}:${port}
+  tls ${certPath} ${keyPath}
+}`,
+    certPath,
+    keyPath,
+    machinesCommand: `machines dns add --domain ${domain} --target-host ${targetHost} --port ${port} --json`,
+    sudoRequired: true
+  };
+}
+function registerMachinesDns(input) {
+  const plan = createLocalSetupPlan(input);
+  const args = [
+    "dns",
+    "add",
+    "--domain",
+    plan.domain,
+    "--target-host",
+    plan.targetHost,
+    "--port",
+    String(plan.port),
+    "--json"
+  ];
+  const result = spawnSync2("machines", args, { encoding: "utf-8" });
+  return {
+    command: `machines ${args.join(" ")}`,
+    status: result.status,
+    stdout: result.stdout || "",
+    stderr: result.stderr || ""
+  };
+}
+
 // src/pg-migrations.ts
 var PG_MIGRATIONS = [
   `
@@ -3388,7 +3448,7 @@ var PG_MIGRATIONS = [
 // src/cli/index.ts
 function getPackageVersion() {
   try {
-    const pkgPath = join4(dirname3(fileURLToPath(import.meta.url)), "..", "..", "package.json");
+    const pkgPath = join5(dirname3(fileURLToPath(import.meta.url)), "..", "..", "package.json");
     return JSON.parse(readFileSync3(pkgPath, "utf-8")).version || "0.0.0";
   } catch {
     return "0.0.0";
@@ -3435,7 +3495,7 @@ function formatLink(link) {
   return `${source_default.green(link.short_url || `${link.hostname}/${link.slug}`)} ${source_default.dim("->")} ${link.destination_url}`;
 }
 function commandExists(command) {
-  const result = spawnSync2("which", [command], { encoding: "utf-8" });
+  const result = spawnSync3("which", [command], { encoding: "utf-8" });
   return result.status === 0;
 }
 program2.name("shortlinks").description("CLI-only shortlink manager with custom domains, click tracking, Cloudflare helpers, and cloud sync").version(getPackageVersion()).option("--db <path>", "SQLite database path").option("-j, --json", "Output JSON for agents and scripts");
@@ -3814,6 +3874,42 @@ cloudCmd.command("status").description("Show local and cloud configuration healt
     handleError(error);
   }
 });
+var localCmd = program2.command("local").description("Local domain setup helpers");
+localCmd.command("plan <domain>").description("Render hosts and reverse-proxy setup for a local shortlink domain").option("--port <port>", "Local redirect server port", "8787").option("--target-host <host>", "Local target host", "127.0.0.1").option("-j, --json", "Output JSON").action((domain, opts) => {
+  try {
+    const plan = createLocalSetupPlan({
+      domain,
+      port: Number(opts.port),
+      targetHost: opts.targetHost
+    });
+    print(plan, opts, () => console.log(JSON.stringify(plan, null, 2)));
+  } catch (error) {
+    handleError(error);
+  }
+});
+localCmd.command("setup <domain>").description("Record local domain mapping with machines and print remaining sudo-only setup").option("--port <port>", "Local redirect server port", "8787").option("--target-host <host>", "Local target host", "127.0.0.1").option("--skip-machines", "Do not call machines dns add").option("-j, --json", "Output JSON").action((domain, opts) => {
+  try {
+    const plan = createLocalSetupPlan({
+      domain,
+      port: Number(opts.port),
+      targetHost: opts.targetHost
+    });
+    const machines = opts.skipMachines ? null : registerMachinesDns({
+      domain,
+      port: Number(opts.port),
+      targetHost: opts.targetHost
+    });
+    const result = { plan, machines };
+    print(result, opts, () => {
+      if (machines && machines.status !== 0) {
+        console.error(source_default.yellow(machines.stderr.trim() || "machines dns add failed"));
+      }
+      console.log(JSON.stringify(result, null, 2));
+    });
+  } catch (error) {
+    handleError(error);
+  }
+});
 program2.command("doctor").description("Check local shortlinks tooling and integration readiness").option("-j, --json", "Output JSON").action((opts) => {
   try {
     const stats = withStore((store) => store.totalStats());
@@ -3832,6 +3928,8 @@ program2.command("doctor").description("Check local shortlinks tooling and integ
       },
       environment: {
         cloudflare_api_token_present: Boolean(process.env.CLOUDFLARE_API_TOKEN),
+        cloudflare_api_key_present: Boolean(process.env.CLOUDFLARE_API_KEY),
+        cloudflare_email_present: Boolean(process.env.CLOUDFLARE_EMAIL),
         shortlinks_origin_present: Boolean(process.env.SHORTLINKS_ORIGIN)
       }
     };

package/dist/cloudflare.d.ts

@@ -36,7 +36,7 @@ export declare function writeWorkerFiles(options?: {
     workerPath: string;
     wranglerPath: string;
 };
-export declare function findCloudflareZoneId(hostname: string, token: string): Promise<string>;
+export declare function findCloudflareZoneId(hostname: string, token?: string): Promise<string>;
 export declare function upsertCloudflareDnsRecord(options: CloudflareDnsOptions): Promise<CloudflareSetupPlan | {
     id: string;
     action: "created" | "updated";

package/dist/cloudflare.js

@@ -87,11 +87,25 @@ SHORTLINKS_ORIGIN = "${options.origin || "https://shortlinks.example.com"}"
 `);
   return { workerPath, wranglerPath };
 }
+function cloudflareAuthHeaders(token) {
+  const apiToken = token || process.env.CLOUDFLARE_API_TOKEN;
+  if (apiToken)
+    return { authorization: `Bearer ${apiToken}` };
+  const apiKey = process.env.CLOUDFLARE_API_KEY;
+  const email = process.env.CLOUDFLARE_EMAIL;
+  if (apiKey && email) {
+    return {
+      "x-auth-key": apiKey,
+      "x-auth-email": email
+    };
+  }
+  throw new Error("Cloudflare auth is required: set CLOUDFLARE_API_TOKEN, or CLOUDFLARE_API_KEY plus CLOUDFLARE_EMAIL.");
+}
 async function cloudflareRequest(token, path, init = {}) {
   const response = await fetch(`https://api.cloudflare.com/client/v4${path}`, {
     ...init,
     headers: {
-      authorization: `Bearer ${token}`,
+      ...cloudflareAuthHeaders(token),
       "content-type": "application/json",
       ...init.headers || {}
     }
@@ -129,8 +143,6 @@ async function upsertCloudflareDnsRecord(options) {
   });
   if (options.dryRun)
     return plan;
-  if (!token)
-    throw new Error("CLOUDFLARE_API_TOKEN is required unless --dry-run is used.");
   const zoneId = options.zoneId || await findCloudflareZoneId(plan.hostname, token);
   const existing = await cloudflareRequest(token, `/zones/${zoneId}/dns_records?type=CNAME&name=${encodeURIComponent(plan.hostname)}`);
   const payload = JSON.stringify(plan.dnsRecord);

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export { ShortlinksDatabase, SQLITE_MIGRATIONS, makeId, now } from "./database.j
 export { ShortlinksStore } from "./store.js";
 export { createShortlinksHandler, serveShortlinks } from "./server.js";
 export { createCloudflarePlan, generateWorkerScript, writeWorkerFiles, upsertCloudflareDnsRecord } from "./cloudflare.js";
+export { createLocalSetupPlan, registerMachinesDns } from "./local.js";
 export { PG_MIGRATIONS } from "./pg-migrations.js";
 export { formatShortUrl, getConfigPath, getDataDir, getDatabasePath, loadConfig, normalizeHostname, saveConfig } from "./config.js";
 export { normalizeSlug, randomToken } from "./slug.js";

package/dist/index.js

@@ -656,11 +656,25 @@ SHORTLINKS_ORIGIN = "${options.origin || "https://shortlinks.example.com"}"
 `);
   return { workerPath, wranglerPath };
 }
+function cloudflareAuthHeaders(token) {
+  const apiToken = token || process.env.CLOUDFLARE_API_TOKEN;
+  if (apiToken)
+    return { authorization: `Bearer ${apiToken}` };
+  const apiKey = process.env.CLOUDFLARE_API_KEY;
+  const email = process.env.CLOUDFLARE_EMAIL;
+  if (apiKey && email) {
+    return {
+      "x-auth-key": apiKey,
+      "x-auth-email": email
+    };
+  }
+  throw new Error("Cloudflare auth is required: set CLOUDFLARE_API_TOKEN, or CLOUDFLARE_API_KEY plus CLOUDFLARE_EMAIL.");
+}
 async function cloudflareRequest(token, path, init = {}) {
   const response = await fetch(`https://api.cloudflare.com/client/v4${path}`, {
     ...init,
     headers: {
-      authorization: `Bearer ${token}`,
+      ...cloudflareAuthHeaders(token),
       "content-type": "application/json",
       ...init.headers || {}
     }
@@ -698,8 +712,6 @@ async function upsertCloudflareDnsRecord(options) {
   });
   if (options.dryRun)
     return plan;
-  if (!token)
-    throw new Error("CLOUDFLARE_API_TOKEN is required unless --dry-run is used.");
   const zoneId = options.zoneId || await findCloudflareZoneId(plan.hostname, token);
   const existing = await cloudflareRequest(token, `/zones/${zoneId}/dns_records?type=CNAME&name=${encodeURIComponent(plan.hostname)}`);
   const payload = JSON.stringify(plan.dnsRecord);
@@ -716,6 +728,53 @@ async function upsertCloudflareDnsRecord(options) {
   });
   return { id: created.id, action: "created" };
 }
+// src/local.ts
+import { spawnSync } from "child_process";
+import { homedir as homedir2 } from "os";
+import { join as join4 } from "path";
+function createLocalSetupPlan(input) {
+  const domain = normalizeHostname(input.domain);
+  const targetHost = input.targetHost || "127.0.0.1";
+  const port = input.port || 8787;
+  const certDir = input.certDir || join4(homedir2(), ".hasna", "machines", "certs");
+  const certPath = join4(certDir, `${domain}.pem`);
+  const keyPath = join4(certDir, `${domain}-key.pem`);
+  return {
+    domain,
+    targetHost,
+    port,
+    hostsEntry: `${targetHost} ${domain}`,
+    caddySnippet: `${domain} {
+  reverse_proxy ${targetHost}:${port}
+  tls ${certPath} ${keyPath}
+}`,
+    certPath,
+    keyPath,
+    machinesCommand: `machines dns add --domain ${domain} --target-host ${targetHost} --port ${port} --json`,
+    sudoRequired: true
+  };
+}
+function registerMachinesDns(input) {
+  const plan = createLocalSetupPlan(input);
+  const args = [
+    "dns",
+    "add",
+    "--domain",
+    plan.domain,
+    "--target-host",
+    plan.targetHost,
+    "--port",
+    String(plan.port),
+    "--json"
+  ];
+  const result = spawnSync("machines", args, { encoding: "utf-8" });
+  return {
+    command: `machines ${args.join(" ")}`,
+    status: result.status,
+    stdout: result.stdout || "",
+    stderr: result.stderr || ""
+  };
+}
 // src/pg-migrations.ts
 var PG_MIGRATIONS = [
   `
@@ -793,6 +852,7 @@ export {
   upsertCloudflareDnsRecord,
   serveShortlinks,
   saveConfig,
+  registerMachinesDns,
   randomToken,
   now,
   normalizeSlug,
@@ -805,6 +865,7 @@ export {
   generateWorkerScript,
   formatShortUrl,
   createShortlinksHandler,
+  createLocalSetupPlan,
   createCloudflarePlan,
   ShortlinksStore,
   ShortlinksDatabase,

package/dist/local.d.ts

@@ -0,0 +1,27 @@
+export interface LocalSetupPlan {
+    domain: string;
+    targetHost: string;
+    port: number;
+    hostsEntry: string;
+    caddySnippet: string;
+    certPath: string;
+    keyPath: string;
+    machinesCommand: string;
+    sudoRequired: boolean;
+}
+export declare function createLocalSetupPlan(input: {
+    domain: string;
+    port?: number;
+    targetHost?: string;
+    certDir?: string;
+}): LocalSetupPlan;
+export declare function registerMachinesDns(input: {
+    domain: string;
+    port?: number;
+    targetHost?: string;
+}): {
+    command: string;
+    status: number | null;
+    stdout: string;
+    stderr: string;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/shortlinks",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "CLI-only shortlink manager for custom domains, click tracking, Cloudflare setup, and @hasna cloud sync",
   "type": "module",
   "main": "dist/index.js",