doomain 0.1.7 → 0.1.9

package/README.md

@@ -14,7 +14,7 @@ Use the interactive wizard when working by hand. Use explicit commands with `--j
 - DNS provider inference by longest matching configured zone.
 - Dry-run plans before writing changes.
 - DNS propagation and Vercel verification wait loop.
-- DNS provider support for Spaceship, Namecheap, and Cloudflare.
+- DNS provider support for Spaceship, Namecheap, Cloudflare, and Hostinger.
 
 ## Install
 
@@ -93,6 +93,7 @@ Doomain stores local credentials in `~/.doomain/config.json` with `0600` file pe
 | Spaceship | `spaceship` | `apiKey`, `apiSecret` | `SPACESHIP_API_KEY`, `SPACESHIP_API_SECRET` | API key needs domain read access and DNS record read/write access. |
 | Namecheap | `namecheap` | `apiUser`, `apiKey`, `clientIp` | `NAMECHEAP_API_USER`, `NAMECHEAP_API_KEY`, `NAMECHEAP_CLIENT_IP` | API access must be enabled and `clientIp` must be your whitelisted public IPv4. Optional: `username`, `sandbox`. |
 | Cloudflare | `cloudflare` | `apiToken`, `accountId` | `CLOUDFLARE_API_TOKEN`, `CLOUDFLARE_ACCOUNT_ID` | API token needs `Zone:Read` and `DNS:Edit`. Vercel records are written as DNS-only records, not proxied. |
+| Hostinger | `hostinger` | `apiToken` | `HOSTINGER_API_TOKEN` | API token needs access to domain portfolio and DNS zone records. |
 
 ### Spaceship
 
@@ -139,6 +140,15 @@ doomain providers connect cloudflare \
 
 Cloudflare records created for Vercel `A`, `AAAA`, and `CNAME` targets are set to `proxied: false` so Vercel can validate the domain.
 
+### Hostinger
+
+```bash
+doomain providers connect hostinger \
+  --credential apiToken=your_hostinger_api_token
+```
+
+Create Hostinger API tokens from hPanel Account > API. Doomain lists active zones from the Hostinger domain portfolio and updates records through the DNS zone API.
+
 ## Linking Domains
 
 You can pass the full target domain as a positional argument:
@@ -373,6 +383,7 @@ Saves DNS provider credentials locally.
 ```bash
 doomain providers connect cloudflare -c apiToken=token -c accountId=account_id
 doomain providers connect namecheap -c apiUser=user -c apiKey=key -c clientIp=127.0.0.1 --json
+doomain providers connect hostinger -c apiToken=token --json
 doomain providers connect spaceship --api-key key --api-secret secret
 ```
 
@@ -495,6 +506,12 @@ CLOUDFLARE_API_TOKEN
 CLOUDFLARE_ACCOUNT_ID
 ```
 
+Hostinger:
+
+```bash
+HOSTINGER_API_TOKEN
+```
+
 Doomain defaults and config:
 
 ```bash
@@ -528,7 +545,7 @@ The selected provider does not have a DNS zone matching the target domain. Check
 
 `PROVIDER_ZONE_AMBIGUOUS`
 
-More than one configured provider has the same best matching zone. Re-run with `--provider cloudflare`, `--provider namecheap`, or `--provider spaceship`.
+More than one configured provider has the same best matching zone. Re-run with `--provider cloudflare`, `--provider namecheap`, `--provider spaceship`, or `--provider hostinger`.
 
 Namecheap authentication or permission errors
 
@@ -538,6 +555,14 @@ Cloudflare permission errors
 
 Make sure the API token has `Zone:Read` and `DNS:Edit` permissions for the account that owns the zones.
 
+Hostinger authentication errors
+
+Make sure the API token is active and can access the domains you want Doomain to manage.
+
+Hostinger DNS zone not found
+
+Make sure the domain is active in Hostinger before linking it. Domains shown as `pending_setup` in Hostinger's portfolio API are not writable through the DNS zone API yet.
+
 DNS propagation timeout
 
 The DNS records may have been saved even if Vercel verification timed out. Check the domain in Vercel, inspect records with `doomain domains list`, or re-run verification with `doomain verify`.

package/dist/commands/schema.js

@@ -1,5 +1,5 @@
 import { Args, Command } from '@oclif/core';
-import { getCommandSchema } from '../lib/command-schema.js';
+import { getCommandSchemaForAgents } from '../lib/command-schema.js';
 import { jsonFlag } from '../lib/flags.js';
 import { createOutput, outputError } from '../lib/output.js';
 export default class Schema extends Command {
@@ -14,7 +14,7 @@ export default class Schema extends Command {
         const { args, flags } = await this.parse(Schema);
         const out = createOutput({ json: flags.json });
         try {
-            const schema = getCommandSchema(args.command);
+            const schema = await getCommandSchemaForAgents(args.command);
             if (!schema)
                 throw new Error(`Unknown command schema: ${args.command}`);
             if (!out.json)

package/dist/lib/command-schema.d.ts

@@ -1,8 +1,16 @@
+import { type ProviderStatus } from './providers/status.js';
+export type ProviderConnectionStatus = Pick<ProviderStatus, 'configured' | 'default' | 'displayName' | 'docsUrl' | 'id'>;
 export interface CommandSchema {
     name: string;
     description: string;
     examples: string[];
     agentHint?: string;
+    agentInstructions?: string[];
+    agentQuickstart?: {
+        doNotPreflight: boolean;
+        preferredFirstCommand: string;
+    };
+    configuredProviders?: ProviderConnectionStatus[];
     mutates?: boolean;
     safeForAgents?: boolean;
     flags: Array<{
@@ -15,3 +23,4 @@ export interface CommandSchema {
 }
 export declare const commandSchemas: CommandSchema[];
 export declare function getCommandSchema(name?: string): CommandSchema[] | CommandSchema | undefined;
+export declare function getCommandSchemaForAgents(name?: string): Promise<CommandSchema[] | CommandSchema | undefined>;

package/dist/lib/command-schema.js

@@ -1,3 +1,4 @@
+import { listProviderStatuses } from './providers/status.js';
 export const commandSchemas = [
     {
         name: 'link',
@@ -9,7 +10,16 @@ export const commandSchemas = [
             'doomain link --domain example.com --subdomain app --project my-app --json',
             'doomain link --provider spaceship --domain example.com --apex --project my-app --dry-run --json',
         ],
-        agentHint: 'For agent use, run `doomain link <domain> --json`. The project is inferred from --project, DOOMAIN_PROJECT, config defaults, .vercel/project.json, or nearest package.json name.',
+        agentHint: 'For agent use, try `doomain link <domain> --json` first. Do not inspect project files, run provider status, or use --dry-run unless the user explicitly asks for a preview. The command infers project/provider and returns structured recovery errors when inference fails.',
+        agentInstructions: [
+            'When the user asks to add or link a domain, run `doomain link <domain> --json` first.',
+            'Do not run `providers status`, `projects list`, `--help`, or `--dry-run` before the first link attempt unless the user asks for a preview or diagnosis.',
+            'Only run follow-up commands when the JSON error includes a recovery action that requires them.',
+        ],
+        agentQuickstart: {
+            doNotPreflight: true,
+            preferredFirstCommand: 'doomain link <domain> --json',
+        },
         mutates: true,
         safeForAgents: true,
         flags: [
@@ -19,7 +29,7 @@ export const commandSchemas = [
             { name: 'subdomain', type: 'string', description: 'Subdomain to add.' },
             { name: 'apex', type: 'boolean', description: 'Use the root/apex domain.' },
             { name: 'project', type: 'string', description: 'Vercel project id/name. Optional when project inference succeeds.' },
-            { name: 'dry-run', type: 'boolean', description: 'Preview changes without writing.' },
+            { name: 'dry-run', type: 'boolean', description: 'Preview changes without writing. Intended for human previews; agents should not use this unless explicitly asked.' },
             { name: 'force', type: 'boolean', description: 'Overwrite conflicting DNS records.' },
             { name: 'wait', type: 'boolean', description: 'Wait for DNS and Vercel verification.', default: true },
             { name: 'timeout', type: 'integer', description: 'Wait timeout in seconds.', default: 300 },
@@ -33,6 +43,7 @@ export const commandSchemas = [
             'doomain providers connect spaceship --credential apiKey=key --credential apiSecret=secret --json',
             'doomain providers connect namecheap --credential apiUser=user --credential apiKey=key --credential clientIp=127.0.0.1 --json',
             'doomain providers connect cloudflare --credential apiToken=token --credential accountId=account_id --json',
+            'doomain providers connect hostinger --credential apiToken=token --json',
         ],
         flags: [
             { name: 'json', type: 'boolean', description: 'Output a single JSON object and never prompt.' },
@@ -64,7 +75,7 @@ export const commandSchemas = [
     {
         name: 'providers disconnect',
         description: 'Remove saved DNS provider credentials locally.',
-        examples: ['doomain providers disconnect namecheap --json', 'doomain providers disconnect cloudflare --json'],
+        examples: ['doomain providers disconnect namecheap --json', 'doomain providers disconnect cloudflare --json', 'doomain providers disconnect hostinger --json'],
         flags: [
             { name: 'json', type: 'boolean', description: 'Output a single JSON object and never prompt.' },
         ],
@@ -72,7 +83,7 @@ export const commandSchemas = [
     {
         name: 'providers verify',
         description: 'Verify saved DNS provider credentials.',
-        examples: ['doomain providers verify spaceship --json', 'doomain providers verify namecheap --json'],
+        examples: ['doomain providers verify spaceship --json', 'doomain providers verify namecheap --json', 'doomain providers verify hostinger --json'],
         flags: [
             { name: 'json', type: 'boolean', description: 'Output a single JSON object and never prompt.' },
         ],
@@ -101,3 +112,26 @@ export function getCommandSchema(name) {
         return commandSchemas;
     return commandSchemas.find((schema) => schema.name === name);
 }
+async function configuredProviders() {
+    return (await listProviderStatuses({ verify: false })).map((provider) => ({
+        configured: provider.configured,
+        default: provider.default,
+        displayName: provider.displayName,
+        docsUrl: provider.docsUrl,
+        id: provider.id,
+    }));
+}
+function withProviderConnections(schema, providers) {
+    if (schema.name !== 'link')
+        return schema;
+    return { ...schema, configuredProviders: providers };
+}
+export async function getCommandSchemaForAgents(name) {
+    const schema = getCommandSchema(name);
+    if (!schema)
+        return undefined;
+    const providers = await configuredProviders();
+    if (Array.isArray(schema))
+        return schema.map((item) => withProviderConnections(item, providers));
+    return withProviderConnections(schema, providers);
+}

package/dist/lib/link-domain.js

@@ -5,7 +5,7 @@ import { loadConfig } from './config.js';
 import { DoomainError } from './errors.js';
 import { detectLocalVercelProject } from './local-vercel.js';
 import { createProvider, getProviderDefinition, listProviderDefinitions } from './providers/registry.js';
-import { isProviderConfigured } from './providers/status.js';
+import { isProviderConfigured, listProviderStatuses } from './providers/status.js';
 import { normalizeDomain, normalizeSubdomain } from './validate.js';
 import { createVercelClient, resolveVercelConfig, VERCEL_APEX_A_RECORD, VERCEL_CNAME_RECORD } from './vercel.js';
 function cleanDnsValue(value) {
@@ -115,6 +115,15 @@ async function resolveZone(provider, zoneDomain) {
     }
     return zone;
 }
+async function providerConnectionDetails() {
+    return (await listProviderStatuses({ verify: false })).map((provider) => ({
+        configured: provider.configured,
+        default: provider.default,
+        displayName: provider.displayName,
+        docsUrl: provider.docsUrl,
+        id: provider.id,
+    }));
+}
 function resolveRequestedDomain(opts) {
     if (opts.apex && opts.subdomain) {
         throw new DoomainError('INVALID_INPUT', 'Use either --apex or --subdomain, not both.');
@@ -168,7 +177,11 @@ async function loadConfiguredProviderZones(providerId) {
     const config = await loadConfig();
     const definitions = listProviderDefinitions().filter((definition) => isProviderConfigured(definition, config));
     if (definitions.length === 0) {
-        throw new DoomainError('CONFIG_NOT_FOUND', 'No DNS provider is configured. Run `doomain providers connect` first.');
+        throw new DoomainError('CONFIG_NOT_FOUND', 'No DNS provider is configured. Run `doomain providers connect` first.', {
+            configuredProviders: await providerConnectionDetails(),
+            recovery: 'Connect the DNS provider that owns this domain, then retry `doomain link <domain> --json`.',
+            suggestedCommands: ['doomain providers connect', 'doomain link <domain> --json'],
+        });
     }
     const results = await Promise.all(definitions.map(async (definition) => {
         try {
@@ -206,7 +219,13 @@ async function resolveProviderTarget(input) {
         const providerMessage = input.provider
             ? `${getProviderDefinition(input.provider).displayName} does not have a matching DNS zone for ${requested.fullDomain}.`
             : `No configured DNS provider has a matching DNS zone for ${requested.fullDomain}.`;
-        throw new DoomainError('PROVIDER_ZONE_NOT_FOUND', providerMessage, { domain: requested.fullDomain, providers: zones.searched });
+        throw new DoomainError('PROVIDER_ZONE_NOT_FOUND', providerMessage, {
+            configuredProviders: await providerConnectionDetails(),
+            domain: requested.fullDomain,
+            recovery: 'Retry with --provider <id> only if another configured provider owns this zone. Otherwise connect the DNS provider that owns this domain.',
+            searchedZones: zones.searched,
+            suggestedCommands: [`doomain link ${requested.fullDomain} --provider <id> --json`, 'doomain providers connect'],
+        });
     }
     const bestLength = matches[0].zone.name.length;
     const bestMatches = matches.filter((candidate) => candidate.zone.name.length === bestLength);

package/dist/lib/providers/hostinger/index.d.ts

@@ -0,0 +1,23 @@
+import type { DnsChange, DnsChangePlan, DnsProvider, DnsProviderDefinition, DnsRecord, DnsRecordInput, DnsZone, ProviderCapabilities, ProviderContext, ProviderHealth } from '../types.js';
+export declare class HostingerProvider implements DnsProvider {
+    readonly capabilities: ProviderCapabilities;
+    readonly id = "hostinger";
+    readonly name = "Hostinger";
+    private readonly http;
+    constructor(context: ProviderContext);
+    verifyCredentials(): Promise<ProviderHealth>;
+    listZones(): Promise<DnsZone[]>;
+    getZone(domain: string): Promise<DnsZone | null>;
+    listRecords(zone: DnsZone): Promise<DnsRecord[]>;
+    planChanges(zone: DnsZone, desired: DnsRecordInput[], opts?: {
+        force?: boolean;
+    }): Promise<DnsChangePlan>;
+    applyChanges(zone: DnsZone, plan: DnsChangePlan): Promise<{
+        applied: DnsChange[];
+        skipped: DnsRecordInput[];
+    }>;
+    upsertRecord(zone: DnsZone, record: DnsRecordInput): Promise<DnsRecord>;
+    deleteRecord(zone: DnsZone, record: DnsRecord): Promise<void>;
+    private putRecords;
+}
+export declare const hostingerProviderDefinition: DnsProviderDefinition;

package/dist/lib/providers/hostinger/index.js

@@ -0,0 +1,162 @@
+import { normalizeDomain } from '../../validate.js';
+import { createProviderHttpClient } from '../core/http.js';
+import { assertNoConflicts, planDnsChanges } from '../core/planner.js';
+const HOSTINGER_API_URL = 'https://developers.hostinger.com';
+const capabilities = {
+    defaultTtl: 14_400,
+    recordTypes: ['A', 'AAAA', 'CNAME', 'MX', 'TXT'],
+    supportsApexCname: false,
+    supportsBulkWrites: true,
+    supportsPagination: false,
+    supportsProxying: false,
+    supportsRecordIds: false,
+};
+function isSupportedRecordType(type) {
+    return capabilities.recordTypes.includes(type);
+}
+function cleanRecordName(name, zoneName) {
+    const normalized = name.trim().toLowerCase().replace(/\.$/, '');
+    const normalizedZone = normalizeDomain(zoneName);
+    if (normalized === '@' || normalized === normalizedZone)
+        return '@';
+    if (normalized.endsWith(`.${normalizedZone}`))
+        return normalized.slice(0, -(normalizedZone.length + 1)) || '@';
+    return normalized;
+}
+function toZone(domain) {
+    if (!domain.domain)
+        return null;
+    if (domain.status && domain.status !== 'active')
+        return null;
+    try {
+        const name = normalizeDomain(domain.domain);
+        return { id: name, metadata: { hostinger: domain }, name };
+    }
+    catch {
+        return null;
+    }
+}
+function toDnsRecords(record, zone) {
+    if (!record.name || !record.type || !isSupportedRecordType(record.type))
+        return [];
+    const name = cleanRecordName(record.name, zone.name);
+    const type = record.type;
+    return (record.records ?? []).flatMap((item) => {
+        const content = item.content;
+        if (!content || item.is_disabled)
+            return [];
+        return [
+            {
+                metadata: { hostinger: { ...record, records: [item] } },
+                name,
+                ttl: record.ttl,
+                type,
+                value: content,
+            },
+        ];
+    });
+}
+function toHostingerRecord(record) {
+    return {
+        name: record.name,
+        records: [{ content: record.value }],
+        ttl: record.ttl ?? capabilities.defaultTtl,
+        type: record.type,
+    };
+}
+function deleteFilter(record) {
+    return { name: record.name, type: record.type };
+}
+export class HostingerProvider {
+    capabilities = capabilities;
+    id = 'hostinger';
+    name = 'Hostinger';
+    http;
+    constructor(context) {
+        this.http = createProviderHttpClient({
+            baseUrl: HOSTINGER_API_URL,
+            errorMessages: {
+                401: 'Hostinger rejected the API token. Re-run `doomain providers connect hostinger` with a valid token.',
+                404: 'Hostinger could not find a writable DNS zone for this domain. Make sure the domain is active in Hostinger before linking it.',
+                422: 'Hostinger rejected the DNS record payload.',
+                429: 'Hostinger rate limit exceeded. Try again later.',
+            },
+            headers: { Authorization: `Bearer ${context.credentials.apiToken}` },
+            providerId: this.id,
+            signal: context.signal,
+        });
+    }
+    async verifyCredentials() {
+        await this.listZones();
+        return { ok: true };
+    }
+    async listZones() {
+        const domains = await this.http.request('/api/domains/v1/portfolio');
+        return domains.flatMap((domain) => {
+            const zone = toZone(domain);
+            return zone ? [zone] : [];
+        });
+    }
+    async getZone(domain) {
+        const normalized = normalizeDomain(domain);
+        const zones = await this.listZones();
+        return zones.find((zone) => zone.name === normalized) ?? null;
+    }
+    async listRecords(zone) {
+        const records = await this.http.request(`/api/dns/v1/zones/${encodeURIComponent(zone.name)}`);
+        return records.flatMap((record) => toDnsRecords(record, zone));
+    }
+    async planChanges(zone, desired, opts = {}) {
+        return planDnsChanges({ desired, existing: await this.listRecords(zone), force: opts.force, providerId: this.id, zone });
+    }
+    async applyChanges(zone, plan) {
+        assertNoConflicts(this.id, plan);
+        const applied = [];
+        const skipped = [];
+        for (const change of plan.changes) {
+            if (change.action === 'skip') {
+                skipped.push(change.record);
+                continue;
+            }
+            if (change.action === 'delete')
+                await this.deleteRecord(zone, change.existing);
+            else
+                await this.putRecords(zone, [change.record], change.action === 'update');
+            applied.push(change);
+        }
+        return { applied, skipped };
+    }
+    async upsertRecord(zone, record) {
+        await this.putRecords(zone, [record], true);
+        return { ...record, ttl: record.ttl ?? capabilities.defaultTtl };
+    }
+    async deleteRecord(zone, record) {
+        await this.http.request(`/api/dns/v1/zones/${encodeURIComponent(zone.name)}`, {
+            body: { filters: [deleteFilter(record)] },
+            method: 'DELETE',
+        });
+    }
+    async putRecords(zone, records, overwrite) {
+        await this.http.request(`/api/dns/v1/zones/${encodeURIComponent(zone.name)}`, {
+            body: { overwrite, zone: records.map(toHostingerRecord) },
+            method: 'PUT',
+        });
+    }
+}
+export const hostingerProviderDefinition = {
+    capabilities,
+    credentials: [{ env: 'HOSTINGER_API_TOKEN', key: 'apiToken', label: 'API token', required: true, secret: true }],
+    displayName: 'Hostinger',
+    docsUrl: 'https://developers.hostinger.com/',
+    id: 'hostinger',
+    name: 'Hostinger',
+    setup: {
+        notes: [
+            'Create a Hostinger API token from hPanel Account > API with access to the domains you want Doomain to manage.',
+            'Doomain uses the Hostinger domain portfolio API to infer zones and the DNS zone API to update records.',
+        ],
+    },
+    create(context) {
+        return new HostingerProvider(context);
+    },
+};

package/dist/lib/providers/registry.js

@@ -2,9 +2,10 @@ import { DoomainError } from '../errors.js';
 import { ensureProviderId } from '../validate.js';
 import { cloudflareProviderDefinition } from './cloudflare/index.js';
 import { createProviderContext } from './core/config.js';
+import { hostingerProviderDefinition } from './hostinger/index.js';
 import { namecheapProviderDefinition } from './namecheap/index.js';
 import { spaceshipProviderDefinition } from './spaceship/index.js';
-const definitions = [spaceshipProviderDefinition, namecheapProviderDefinition, cloudflareProviderDefinition];
+const definitions = [spaceshipProviderDefinition, namecheapProviderDefinition, cloudflareProviderDefinition, hostingerProviderDefinition];
 export function listProviderDefinitions() {
     return definitions;
 }

package/oclif.manifest.json

@@ -301,41 +301,6 @@
         "list.js"
       ]
     },
-    "projects:list": {
-      "aliases": [],
-      "args": {},
-      "description": "List Vercel projects.",
-      "flags": {
-        "json": {
-          "description": "Output a single JSON object and never prompt.",
-          "name": "json",
-          "allowNo": false,
-          "type": "boolean"
-        },
-        "search": {
-          "description": "Filter projects by search term.",
-          "name": "search",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        }
-      },
-      "hasDynamicHelp": false,
-      "hiddenAliases": [],
-      "id": "projects:list",
-      "pluginAlias": "doomain",
-      "pluginName": "doomain",
-      "pluginType": "core",
-      "strict": true,
-      "enableJsonFlag": false,
-      "isESM": true,
-      "relativePath": [
-        "dist",
-        "commands",
-        "projects",
-        "list.js"
-      ]
-    },
     "providers:add": {
       "aliases": [],
       "args": {
@@ -596,6 +561,41 @@
         "verify.js"
       ]
     },
+    "projects:list": {
+      "aliases": [],
+      "args": {},
+      "description": "List Vercel projects.",
+      "flags": {
+        "json": {
+          "description": "Output a single JSON object and never prompt.",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "search": {
+          "description": "Filter projects by search term.",
+          "name": "search",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "projects:list",
+      "pluginAlias": "doomain",
+      "pluginName": "doomain",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "projects",
+        "list.js"
+      ]
+    },
     "auth:logout:vercel": {
       "aliases": [],
       "args": {},
@@ -630,5 +630,5 @@
       ]
     }
   },
-  "version": "0.1.7"
+  "version": "0.1.9"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "doomain",
   "description": "Link your vercel project and domain in seconds",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "author": "Crafter Station",
   "packageManager": "bun@1.3.13",
   "bin": {