hatchkit 0.1.1

package/dist/templates/ml-clients/custom-hf.ts.hbs

@@ -0,0 +1,20 @@
+/**
+ * Client for custom HuggingFace model: {{customHfModelId}}
+ * Deployed to: {{gpuPlatform}}
+ */
+
+const ENDPOINT = process.env.ML_CUSTOM_HF_ENDPOINT || "";
+
+export async function predict(input: unknown): Promise<unknown> {
+  const res = await fetch(ENDPOINT, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ input }),
+  });
+
+  if (!res.ok) {
+    throw new Error(`ML prediction failed: ${res.status} ${res.statusText}`);
+  }
+
+  return res.json();
+}

package/dist/templates/ml-clients/image-recognition.ts.hbs

@@ -0,0 +1,22 @@
+import { config } from "../config.js";
+
+export interface RecognitionResult {
+  label: string;
+  score: number;
+}
+
+export async function recognizeImage(imageBuffer: Buffer): Promise<RecognitionResult[]> {
+  const formData = new FormData();
+  formData.append("file", new Blob([imageBuffer]));
+
+  const res = await fetch(config.ML_IMAGE_RECOGNITION_ENDPOINT, {
+    method: "POST",
+    body: formData,
+  });
+
+  if (!res.ok) {
+    throw new Error(`Image recognition failed: ${res.status} ${res.statusText}`);
+  }
+
+  return res.json() as Promise<RecognitionResult[]>;
+}

package/dist/templates/ml-clients/subtitles.ts.hbs

@@ -0,0 +1,26 @@
+import { config } from "../config.js";
+
+export interface SubtitleSegment {
+  start: number;
+  end: number;
+  text: string;
+}
+
+export async function generateSubtitles(audioBuffer: Buffer): Promise<{
+  segments: SubtitleSegment[];
+  srt: string;
+}> {
+  const formData = new FormData();
+  formData.append("file", new Blob([audioBuffer]));
+
+  const res = await fetch(config.ML_SUBTITLES_ENDPOINT, {
+    method: "POST",
+    body: formData,
+  });
+
+  if (!res.ok) {
+    throw new Error(`Subtitle generation failed: ${res.status} ${res.statusText}`);
+  }
+
+  return res.json() as Promise<{ segments: SubtitleSegment[]; srt: string }>;
+}

package/dist/utils/coolify-api.d.ts

@@ -0,0 +1,45 @@
+export interface CoolifyServer {
+    id: number;
+    name: string;
+    ip: string;
+    description?: string;
+}
+export interface CoolifyApiOptions {
+    url: string;
+    token: string;
+}
+/** Coolify REST API client. */
+export declare class CoolifyApi {
+    private url;
+    private token;
+    constructor(options: CoolifyApiOptions);
+    private request;
+    /** Test connection and get Coolify version. */
+    getVersion(): Promise<string>;
+    /** List all servers. */
+    listServers(): Promise<CoolifyServer[]>;
+    /** List all projects. */
+    listProjects(): Promise<Array<{
+        id: number;
+        name: string;
+    }>>;
+    /** Create a new project. */
+    createProject(name: string): Promise<{
+        id: number;
+        name: string;
+    }>;
+    /** List Coolify apps/services so callers can resolve a UUID by name. */
+    listApplications(): Promise<Array<{
+        uuid: string;
+        name: string;
+        description?: string;
+    }>>;
+    /** Upsert an env variable on a Coolify application. The Coolify API
+     *  accepts multiple envs in one call so this is idempotent. */
+    setAppEnv(appUuid: string, envs: Record<string, string>, options?: {
+        isPreview?: boolean;
+    }): Promise<void>;
+}
+/** Verify Coolify connection. Returns version string or throws. */
+export declare function verifyCoolify(url: string, token: string): Promise<string>;
+//# sourceMappingURL=coolify-api.d.ts.map

package/dist/utils/coolify-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coolify-api.d.ts","sourceRoot":"","sources":["../../src/utils/coolify-api.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACf;AAED,+BAA+B;AAC/B,qBAAa,UAAU;IACrB,OAAO,CAAC,GAAG,CAAS;IACpB,OAAO,CAAC,KAAK,CAAS;gBAEV,OAAO,EAAE,iBAAiB;YAKxB,OAAO;IAqBrB,+CAA+C;IACzC,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC;IAKnC,wBAAwB;IAClB,WAAW,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC;IAkB7C,yBAAyB;IACnB,YAAY,IAAI,OAAO,CAAC,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAIlE,4BAA4B;IACtB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAIxE,wEAAwE;IAClE,gBAAgB,IAAI,OAAO,CAAC,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAI9F;mEAC+D;IACzD,SAAS,CACb,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAA;KAAO,GACpC,OAAO,CAAC,IAAI,CAAC;CAYjB;AAED,mEAAmE;AACnE,wBAAsB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAG/E"}

package/dist/utils/coolify-api.js

@@ -0,0 +1,72 @@
+/** Coolify REST API client. */
+export class CoolifyApi {
+    url;
+    token;
+    constructor(options) {
+        this.url = options.url.replace(/\/$/, "");
+        this.token = options.token;
+    }
+    async request(method, path, body) {
+        const res = await fetch(`${this.url}/api/v1${path}`, {
+            method,
+            headers: {
+                Authorization: `Bearer ${this.token}`,
+                "Content-Type": "application/json",
+                Accept: "application/json",
+            },
+            body: body ? JSON.stringify(body) : undefined,
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            throw new Error(`Coolify API ${method} ${path} failed: ${res.status} ${res.statusText}${text ? ` — ${text}` : ""}`);
+        }
+        return res.json();
+    }
+    /** Test connection and get Coolify version. */
+    async getVersion() {
+        const data = await this.request("GET", "/version");
+        return data.version;
+    }
+    /** List all servers. */
+    async listServers() {
+        const data = await this.request("GET", "/servers");
+        return data.map((s) => ({
+            id: s.id,
+            name: s.name,
+            ip: s.ip,
+            description: s.description,
+        }));
+    }
+    /** List all projects. */
+    async listProjects() {
+        return this.request("GET", "/projects");
+    }
+    /** Create a new project. */
+    async createProject(name) {
+        return this.request("POST", "/projects", { name });
+    }
+    /** List Coolify apps/services so callers can resolve a UUID by name. */
+    async listApplications() {
+        return this.request("GET", "/applications");
+    }
+    /** Upsert an env variable on a Coolify application. The Coolify API
+     *  accepts multiple envs in one call so this is idempotent. */
+    async setAppEnv(appUuid, envs, options = {}) {
+        const body = {
+            data: Object.entries(envs).map(([key, value]) => ({
+                key,
+                value,
+                is_preview: options.isPreview ?? false,
+                is_build_time: false,
+                is_literal: true,
+            })),
+        };
+        await this.request("PATCH", `/applications/${appUuid}/envs/bulk`, body);
+    }
+}
+/** Verify Coolify connection. Returns version string or throws. */
+export async function verifyCoolify(url, token) {
+    const api = new CoolifyApi({ url, token });
+    return api.getVersion();
+}
+//# sourceMappingURL=coolify-api.js.map

package/dist/utils/coolify-api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coolify-api.js","sourceRoot":"","sources":["../../src/utils/coolify-api.ts"],"names":[],"mappings":"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"}

package/dist/utils/errors.d.ts

@@ -0,0 +1,2 @@
+export declare function explainFsError(err: unknown, context: string): string;
+//# sourceMappingURL=errors.d.ts.map

package/dist/utils/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"AAeA,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAsBpE"}

package/dist/utils/errors.js

@@ -0,0 +1,31 @@
+/*
+ * Error-message helpers.
+ *
+ * `explainFsError` maps common Node I/O error codes to actionable
+ * recovery hints. The returned string is safe to display to users
+ * (no internal paths beyond what the error already contains).
+ */
+export function explainFsError(err, context) {
+    const e = err;
+    const path = e.path ? ` at ${e.path}` : "";
+    switch (e.code) {
+        case "EACCES":
+            return `${context}: permission denied${path}. Fix: check the parent directory's write permissions, or run with sufficient privileges.`;
+        case "EPERM":
+            return `${context}: operation not permitted${path}. Fix: the file may be locked or owned by another user; check ownership.`;
+        case "ENOSPC":
+            return `${context}: out of disk space${path}. Fix: free up space and retry.`;
+        case "ENOENT":
+            return `${context}: file not found${path}. Fix: make sure the starter submodule is initialized (\`git submodule update --init\` in the monorepo root).`;
+        case "EEXIST":
+            return `${context}: file already exists${path}. Fix: move or remove it, then retry.`;
+        case "EROFS":
+            return `${context}: filesystem is read-only${path}. Fix: scaffold into a writable location.`;
+        case "EMFILE":
+        case "ENFILE":
+            return `${context}: too many open files. Fix: close other processes or raise \`ulimit -n\`.`;
+        default:
+            return `${context}: ${e.message ?? String(err)}`;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/utils/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AASH,MAAM,UAAU,cAAc,CAAC,GAAY,EAAE,OAAe;IAC1D,MAAM,CAAC,GAAG,GAAiB,CAAC;IAC5B,MAAM,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC3C,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC;QACf,KAAK,QAAQ;YACX,OAAO,GAAG,OAAO,sBAAsB,IAAI,2FAA2F,CAAC;QACzI,KAAK,OAAO;YACV,OAAO,GAAG,OAAO,4BAA4B,IAAI,0EAA0E,CAAC;QAC9H,KAAK,QAAQ;YACX,OAAO,GAAG,OAAO,sBAAsB,IAAI,iCAAiC,CAAC;QAC/E,KAAK,QAAQ;YACX,OAAO,GAAG,OAAO,mBAAmB,IAAI,+GAA+G,CAAC;QAC1J,KAAK,QAAQ;YACX,OAAO,GAAG,OAAO,wBAAwB,IAAI,uCAAuC,CAAC;QACvF,KAAK,OAAO;YACV,OAAO,GAAG,OAAO,4BAA4B,IAAI,2CAA2C,CAAC;QAC/F,KAAK,QAAQ,CAAC;QACd,KAAK,QAAQ;YACX,OAAO,GAAG,OAAO,2EAA2E,CAAC;QAC/F;YACE,OAAO,GAAG,OAAO,KAAK,CAAC,CAAC,OAAO,IAAI,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;IACrD,CAAC;AACH,CAAC"}

package/dist/utils/exec.d.ts

@@ -0,0 +1,23 @@
+export interface ExecResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+/** Run a shell command with a spinner. */
+export declare function exec(command: string, args: string[], options?: {
+    cwd?: string;
+    env?: Record<string, string>;
+    spinner?: string;
+    silent?: boolean;
+}): Promise<ExecResult>;
+/** Run a shell command and return true if exit code is 0. */
+export declare function execOk(command: string, args: string[], options?: {
+    cwd?: string;
+    env?: Record<string, string>;
+}): Promise<boolean>;
+/** Run a shell command, stream output to terminal. */
+export declare function execStream(command: string, args: string[], options?: {
+    cwd?: string;
+    env?: Record<string, string>;
+}): Promise<number>;
+//# sourceMappingURL=exec.d.ts.map

package/dist/utils/exec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec.d.ts","sourceRoot":"","sources":["../../src/utils/exec.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,0CAA0C;AAC1C,wBAAsB,IAAI,CACxB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,CAAC,EAAE;IACR,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,GACA,OAAO,CAAC,UAAU,CAAC,CA4BrB;AAED,6DAA6D;AAC7D,wBAAsB,MAAM,CAC1B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GACvD,OAAO,CAAC,OAAO,CAAC,CAGlB;AAED,sDAAsD;AACtD,wBAAsB,UAAU,CAC9B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GACvD,OAAO,CAAC,MAAM,CAAC,CAQjB"}

package/dist/utils/exec.js

@@ -0,0 +1,47 @@
+import { execa } from "execa";
+import ora from "ora";
+/** Run a shell command with a spinner. */
+export async function exec(command, args, options) {
+    const spinner = options?.spinner ? ora(options.spinner).start() : null;
+    try {
+        const result = await execa(command, args, {
+            cwd: options?.cwd,
+            env: { ...process.env, ...options?.env },
+            reject: false,
+        });
+        if (result.exitCode !== 0) {
+            spinner?.fail();
+            if (!options?.silent) {
+                console.error(result.stderr || result.stdout);
+            }
+        }
+        else {
+            spinner?.succeed();
+        }
+        return {
+            stdout: result.stdout,
+            stderr: result.stderr,
+            exitCode: result.exitCode ?? 1,
+        };
+    }
+    catch (error) {
+        spinner?.fail();
+        throw error;
+    }
+}
+/** Run a shell command and return true if exit code is 0. */
+export async function execOk(command, args, options) {
+    const result = await exec(command, args, { ...options, silent: true });
+    return result.exitCode === 0;
+}
+/** Run a shell command, stream output to terminal. */
+export async function execStream(command, args, options) {
+    const result = await execa(command, args, {
+        cwd: options?.cwd,
+        env: { ...process.env, ...options?.env },
+        stdio: "inherit",
+        reject: false,
+    });
+    return result.exitCode ?? 1;
+}
+//# sourceMappingURL=exec.js.map

package/dist/utils/exec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec.js","sourceRoot":"","sources":["../../src/utils/exec.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC;AAC9B,OAAO,GAAG,MAAM,KAAK,CAAC;AAQtB,0CAA0C;AAC1C,MAAM,CAAC,KAAK,UAAU,IAAI,CACxB,OAAe,EACf,IAAc,EACd,OAKC;IAED,MAAM,OAAO,GAAG,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IAEvE,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE;YACxC,GAAG,EAAE,OAAO,EAAE,GAAG;YACjB,GAAG,EAAE,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,GAAG,OAAO,EAAE,GAAG,EAAE;YACxC,MAAM,EAAE,KAAK;SACd,CAAC,CAAC;QAEH,IAAI,MAAM,CAAC,QAAQ,KAAK,CAAC,EAAE,CAAC;YAC1B,OAAO,EAAE,IAAI,EAAE,CAAC;YAChB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC;gBACrB,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,CAAC,CAAC;YAChD,CAAC;QACH,CAAC;aAAM,CAAC;YACN,OAAO,EAAE,OAAO,EAAE,CAAC;QACrB,CAAC;QAED,OAAO;YACL,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,CAAC;SAC/B,CAAC;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,EAAE,IAAI,EAAE,CAAC;QAChB,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED,6DAA6D;AAC7D,MAAM,CAAC,KAAK,UAAU,MAAM,CAC1B,OAAe,EACf,IAAc,EACd,OAAwD;IAExD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,EAAE,GAAG,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;IACvE,OAAO,MAAM,CAAC,QAAQ,KAAK,CAAC,CAAC;AAC/B,CAAC;AAED,sDAAsD;AACtD,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,OAAe,EACf,IAAc,EACd,OAAwD;IAExD,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE;QACxC,GAAG,EAAE,OAAO,EAAE,GAAG;QACjB,GAAG,EAAE,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,GAAG,OAAO,EAAE,GAAG,EAAE;QACxC,KAAK,EAAE,SAAS;QAChB,MAAM,EAAE,KAAK;KACd,CAAC,CAAC;IACH,OAAO,MAAM,CAAC,QAAQ,IAAI,CAAC,CAAC;AAC9B,CAAC"}

package/dist/utils/flags.d.ts

@@ -0,0 +1,17 @@
+import type { ProjectConfig } from "../prompts.js";
+export interface ParsedCreateFlags {
+    /** Non-interactive: accept defaults, fail if a required value with
+     *  no default is missing rather than prompting. */
+    yes: boolean;
+    /** --dry-run — already handled in index.ts but re-parsed here so
+     *  one place knows the full set of supported flags. */
+    dryRun: boolean;
+    /** Preset values parsed from individual flags + --config file. */
+    presets: Partial<ProjectConfig>;
+    /** --no-github / --no-deploy hard-disable those steps regardless of
+     *  what the preset / prompts would say. */
+    forceNoGithub: boolean;
+    forceNoDeploy: boolean;
+}
+export declare function parseCreateFlags(argv: string[]): ParsedCreateFlags;
+//# sourceMappingURL=flags.d.ts.map

package/dist/utils/flags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flags.d.ts","sourceRoot":"","sources":["../../src/utils/flags.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAsB,aAAa,EAAE,MAAM,eAAe,CAAC;AAEvE,MAAM,WAAW,iBAAiB;IAChC;uDACmD;IACnD,GAAG,EAAE,OAAO,CAAC;IACb;2DACuD;IACvD,MAAM,EAAE,OAAO,CAAC;IAChB,kEAAkE;IAClE,OAAO,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;IAChC;+CAC2C;IAC3C,aAAa,EAAE,OAAO,CAAC;IACvB,aAAa,EAAE,OAAO,CAAC;CACxB;AAkBD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,iBAAiB,CA6FlE"}

package/dist/utils/flags.js

@@ -0,0 +1,116 @@
+/*
+ * Command-line flag parsing for `hatchkit create`.
+ *
+ * Keeps the flag surface deliberately small — a few common flags plus
+ * a `--config <path>` escape hatch that reads a JSON file matching
+ * Partial<ProjectConfig>. Flags win over config file; config file
+ * wins over prompt defaults.
+ *
+ * Design choice: don't try to expose every ProjectConfig field as a
+ * flag. The combinatorial space is big and awkward to document. For
+ * anything beyond the common case, point users at `--config <path>`.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+const KNOWN_FEATURES = [
+    "websocket",
+    "stripe",
+    "analytics",
+    "s3",
+    "desktop",
+    "mobile",
+];
+const KNOWN_ML_SERVICES = [
+    "3d-extraction",
+    "subtitles",
+    "image-recognition",
+    "background-removal",
+    "custom-hf",
+];
+export function parseCreateFlags(argv) {
+    const get = (name) => {
+        // Accept both `--name value` and `--name=value`.
+        const equalsIdx = argv.findIndex((a) => a.startsWith(`--${name}=`));
+        if (equalsIdx !== -1)
+            return argv[equalsIdx].slice(name.length + 3);
+        const idx = argv.indexOf(`--${name}`);
+        if (idx === -1 || idx === argv.length - 1)
+            return undefined;
+        const next = argv[idx + 1];
+        return next.startsWith("--") ? undefined : next;
+    };
+    const has = (name) => argv.includes(`--${name}`) || argv.some((a) => a.startsWith(`--${name}=`));
+    const yes = argv.includes("--yes") || argv.includes("-y");
+    const dryRun = argv.includes("--dry-run");
+    const forceNoGithub = argv.includes("--no-github");
+    const forceNoDeploy = argv.includes("--no-deploy");
+    // Start from --config <path> if present, then layer individual flags on top.
+    const presets = {};
+    const configPath = get("config");
+    if (configPath) {
+        const absPath = resolve(configPath);
+        if (!existsSync(absPath)) {
+            throw new Error(`--config file not found: ${absPath}`);
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(absPath, "utf-8"));
+        }
+        catch (err) {
+            throw new Error(`--config file is not valid JSON: ${absPath} (${err.message})`);
+        }
+        if (!parsed || typeof parsed !== "object") {
+            throw new Error(`--config file must be a JSON object: ${absPath}`);
+        }
+        Object.assign(presets, parsed);
+    }
+    const name = get("name");
+    if (name)
+        presets.name = name;
+    const domain = get("domain");
+    if (domain)
+        presets.domain = domain;
+    const features = get("features");
+    if (features !== undefined) {
+        const list = features
+            .split(",")
+            .map((s) => s.trim())
+            .filter(Boolean);
+        const invalid = list.filter((f) => !KNOWN_FEATURES.includes(f));
+        if (invalid.length > 0) {
+            throw new Error(`Unknown --features values: ${invalid.join(", ")}. Valid: ${KNOWN_FEATURES.join(", ")}`);
+        }
+        presets.features = list;
+    }
+    const mlServices = get("ml-services");
+    if (mlServices !== undefined) {
+        const list = mlServices
+            .split(",")
+            .map((s) => s.trim())
+            .filter(Boolean);
+        const invalid = list.filter((f) => !KNOWN_ML_SERVICES.includes(f));
+        if (invalid.length > 0) {
+            throw new Error(`Unknown --ml-services values: ${invalid.join(", ")}. Valid: ${KNOWN_ML_SERVICES.join(", ")}`);
+        }
+        presets.mlServices = list;
+    }
+    const deployTarget = get("deploy-target");
+    if (deployTarget === "existing" || deployTarget === "new") {
+        presets.deployTarget = deployTarget;
+    }
+    else if (deployTarget !== undefined) {
+        throw new Error(`--deploy-target must be 'existing' or 'new' (got '${deployTarget}')`);
+    }
+    if (forceNoGithub)
+        presets.createGithubRepo = false;
+    if (forceNoDeploy)
+        presets.runDeployment = false;
+    // Validate that presets-provided values look right before we pass
+    // them on (the prompt layer would also catch these, but failing
+    // early in non-interactive mode gives a cleaner error).
+    if (has("config") && typeof presets.name !== "string" && yes) {
+        // fine — may still come from --name flag or default
+    }
+    return { yes, dryRun, presets, forceNoGithub, forceNoDeploy };
+}
+//# sourceMappingURL=flags.js.map

package/dist/utils/flags.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flags.js","sourceRoot":"","sources":["../../src/utils/flags.ts"],"names":[],"mappings":"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"}

package/dist/utils/hf-api.d.ts

@@ -0,0 +1,13 @@
+export type ModelPipelineTag = "text-generation" | "text-classification" | "token-classification" | "image-classification" | "object-detection" | "image-segmentation" | "text-to-image" | "image-to-text" | "automatic-speech-recognition" | "translation" | "summarization" | "feature-extraction" | "other";
+export interface HfModelInfo {
+    modelId: string;
+    pipelineTag: ModelPipelineTag;
+    library: string;
+    tags: string[];
+    private: boolean;
+}
+/** Query the HuggingFace Hub API to get model info. */
+export declare function getModelInfo(modelId: string): Promise<HfModelInfo>;
+/** Suggest GPU type based on model pipeline and tags. */
+export declare function suggestGpu(info: HfModelInfo): string;
+//# sourceMappingURL=hf-api.d.ts.map

package/dist/utils/hf-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hf-api.d.ts","sourceRoot":"","sources":["../../src/utils/hf-api.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,gBAAgB,GACxB,iBAAiB,GACjB,qBAAqB,GACrB,sBAAsB,GACtB,sBAAsB,GACtB,kBAAkB,GAClB,oBAAoB,GACpB,eAAe,GACf,eAAe,GACf,8BAA8B,GAC9B,aAAa,GACb,eAAe,GACf,oBAAoB,GACpB,OAAO,CAAC;AAEZ,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,gBAAgB,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,uDAAuD;AACvD,wBAAsB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAyBxE;AAED,yDAAyD;AACzD,wBAAgB,UAAU,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,CAWpD"}

package/dist/utils/hf-api.js

@@ -0,0 +1,30 @@
+/** Query the HuggingFace Hub API to get model info. */
+export async function getModelInfo(modelId) {
+    const res = await fetch(`https://huggingface.co/api/models/${modelId}`);
+    if (!res.ok) {
+        if (res.status === 404) {
+            throw new Error(`Model not found: ${modelId}`);
+        }
+        throw new Error(`HuggingFace API error: ${res.status} ${res.statusText}`);
+    }
+    const data = (await res.json());
+    return {
+        modelId: data.id,
+        pipelineTag: data.pipeline_tag || "other",
+        library: data.library_name || "unknown",
+        tags: data.tags || [],
+        private: data.private || false,
+    };
+}
+/** Suggest GPU type based on model pipeline and tags. */
+export function suggestGpu(info) {
+    if (info.pipelineTag === "text-generation" ||
+        info.tags.some((t) => t.includes("llama") || t.includes("70b"))) {
+        return "A100";
+    }
+    if (info.pipelineTag === "text-to-image" || info.pipelineTag === "image-segmentation") {
+        return "A10G";
+    }
+    return "T4";
+}
+//# sourceMappingURL=hf-api.js.map

package/dist/utils/hf-api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hf-api.js","sourceRoot":"","sources":["../../src/utils/hf-api.ts"],"names":[],"mappings":"AAuBA,uDAAuD;AACvD,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,OAAe;IAChD,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,qCAAqC,OAAO,EAAE,CAAC,CAAC;IAExE,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QACZ,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,oBAAoB,OAAO,EAAE,CAAC,CAAC;QACjD,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,0BAA0B,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,UAAU,EAAE,CAAC,CAAC;IAC5E,CAAC;IAED,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAM7B,CAAC;IAEF,OAAO;QACL,OAAO,EAAE,IAAI,CAAC,EAAE;QAChB,WAAW,EAAG,IAAI,CAAC,YAAiC,IAAI,OAAO;QAC/D,OAAO,EAAE,IAAI,CAAC,YAAY,IAAI,SAAS;QACvC,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,EAAE;QACrB,OAAO,EAAE,IAAI,CAAC,OAAO,IAAI,KAAK;KAC/B,CAAC;AACJ,CAAC;AAED,yDAAyD;AACzD,MAAM,UAAU,UAAU,CAAC,IAAiB;IAC1C,IACE,IAAI,CAAC,WAAW,KAAK,iBAAiB;QACtC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAC/D,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,IAAI,IAAI,CAAC,WAAW,KAAK,eAAe,IAAI,IAAI,CAAC,WAAW,KAAK,oBAAoB,EAAE,CAAC;QACtF,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/utils/ports.d.ts

@@ -0,0 +1,29 @@
+export declare const PORT_RANGES: {
+    server: readonly [5000, 5999];
+    client: readonly [6000, 6999];
+    nativeHmr: readonly [7000, 7999];
+};
+/** Test whether a port is free to bind on 127.0.0.1. Resolves with
+ *  `true` if we could successfully open + immediately close a listener
+ *  on it; `false` if the bind failed for any reason (EADDRINUSE,
+ *  permission, etc.). Always resolves — never throws. */
+export declare function isPortFree(port: number): Promise<boolean>;
+/** Pick a port in [min, max] that is (a) not in the used-ports
+ *  registry and (b) actually free to bind on 127.0.0.1. Scans
+ *  sequentially from a random starting point, wrapping once. Throws
+ *  if every port in the range is either registered or occupied. */
+export declare function pickPort(min: number, max: number, used: Set<number>): Promise<number>;
+export interface ProjectPorts {
+    server: number;
+    client: number;
+    /** Only set when desktop or mobile is selected. */
+    nativeHmr?: number;
+}
+/** Pick a coherent port set for a new project, avoiding ports already
+ *  assigned to prior scaffolds AND ports that are actually busy on the
+ *  host. Caller is responsible for persisting the returned ports into
+ *  the used-ports registry. */
+export declare function pickProjectPorts(used: number[], options: {
+    nativeHmr: boolean;
+}): Promise<ProjectPorts>;
+//# sourceMappingURL=ports.d.ts.map

package/dist/utils/ports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ports.d.ts","sourceRoot":"","sources":["../../src/utils/ports.ts"],"names":[],"mappings":"AAgCA,eAAO,MAAM,WAAW;;;;CAIvB,CAAC;AAEF;;;yDAGyD;AACzD,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAQzD;AAED;;;mEAGmE;AACnE,wBAAsB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAiB3F;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;+BAG+B;AAC/B,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,EAAE;IAAE,SAAS,EAAE,OAAO,CAAA;CAAE,GAC9B,OAAO,CAAC,YAAY,CAAC,CAWvB"}

package/dist/utils/ports.js

@@ -0,0 +1,86 @@
+/*
+ * Port picker.
+ *
+ * At scaffold time we assign each project a fixed set of ports so dev
+ * servers across multiple scaffolded projects don't collide on
+ * localhost. Ports come from three disjoint 1000-slot ranges:
+ *
+ *   server       5000 – 5999   Express API / backend
+ *   client       6000 – 6999   Next.js web dev server
+ *   nativeHmr    7000 – 7999   Next dev server for Capacitor + Electron
+ *                              (only picked when desktop or mobile is
+ *                               selected, so regular web + native can
+ *                               run side-by-side without stomping)
+ *
+ * Two layers of collision avoidance:
+ *   1. The CLI config tracks ports handed out to prior `hatchkit
+ *      create` runs (usedPorts registry) — avoids picking the same
+ *      port twice across scaffolds on this machine.
+ *   2. Each candidate is tested by actually binding to it on
+ *      127.0.0.1. If a non-scaffolded process holds the port (someone
+ *      else's dev server, a system service, etc.) we skip it and try
+ *      the next. This is the bit that makes the picked port "real"
+ *      enough to commit to .env.development.
+ *
+ * The scan order is: pick a random starting point inside the range,
+ * then step forward from there, wrapping at the end. That gives
+ * decent distribution across the range while also feeling like
+ * "auto-increment until free" at the low level.
+ */
+import { createServer } from "node:net";
+export const PORT_RANGES = {
+    server: [5000, 5999],
+    client: [6000, 6999],
+    nativeHmr: [7000, 7999],
+};
+/** Test whether a port is free to bind on 127.0.0.1. Resolves with
+ *  `true` if we could successfully open + immediately close a listener
+ *  on it; `false` if the bind failed for any reason (EADDRINUSE,
+ *  permission, etc.). Always resolves — never throws. */
+export function isPortFree(port) {
+    return new Promise((resolve) => {
+        const server = createServer();
+        server.once("error", () => resolve(false));
+        server.listen(port, "127.0.0.1", () => {
+            server.close(() => resolve(true));
+        });
+    });
+}
+/** Pick a port in [min, max] that is (a) not in the used-ports
+ *  registry and (b) actually free to bind on 127.0.0.1. Scans
+ *  sequentially from a random starting point, wrapping once. Throws
+ *  if every port in the range is either registered or occupied. */
+export async function pickPort(min, max, used) {
+    const span = max - min + 1;
+    const start = Math.floor(Math.random() * span);
+    let registryCollisions = 0;
+    let busyPorts = 0;
+    for (let i = 0; i < span; i++) {
+        const port = min + ((start + i) % span);
+        if (used.has(port)) {
+            registryCollisions++;
+            continue;
+        }
+        if (await isPortFree(port))
+            return port;
+        busyPorts++;
+    }
+    throw new Error(`No free port found in range ${min}-${max} — ${registryCollisions} registered to other scaffolds, ${busyPorts} held by other processes. Run \`hatchkit config reset\` to clear the registry if it's stale.`);
+}
+/** Pick a coherent port set for a new project, avoiding ports already
+ *  assigned to prior scaffolds AND ports that are actually busy on the
+ *  host. Caller is responsible for persisting the returned ports into
+ *  the used-ports registry. */
+export async function pickProjectPorts(used, options) {
+    const usedSet = new Set(used);
+    const server = await pickPort(PORT_RANGES.server[0], PORT_RANGES.server[1], usedSet);
+    usedSet.add(server);
+    const client = await pickPort(PORT_RANGES.client[0], PORT_RANGES.client[1], usedSet);
+    usedSet.add(client);
+    const ports = { server, client };
+    if (options.nativeHmr) {
+        ports.nativeHmr = await pickPort(PORT_RANGES.nativeHmr[0], PORT_RANGES.nativeHmr[1], usedSet);
+    }
+    return ports;
+}
+//# sourceMappingURL=ports.js.map