primitive-admin 1.1.0-alpha.9 → 1.1.0

package/dist/src/lib/template.d.ts

@@ -0,0 +1,170 @@
+export declare function vueTemplateUrl(branch?: string): string;
+export declare function iosTemplateUrl(branch?: string): string;
+declare const IOS_TEMPLATE_URL: string;
+/**
+ * Resolve which template branch `primitive init` scaffolds from — same
+ * precedence as `primitive guides` (see resolveChannelBranch): the
+ * undocumented `PRIMITIVE_TEMPLATE_BRANCH` override (validated), then alpha
+ * server-URL detection, then `main`.
+ */
+export declare function resolveTemplateBranch(serverUrl: string | undefined, override?: string | undefined): string;
+export interface PrepareTemplateOptions {
+    templateUrl?: string;
+    /**
+     * Retried once if the primary URL download fails (e.g. a channel branch
+     * that hasn't been pushed yet returns 404). `onFallback` reports why.
+     */
+    fallbackTemplateUrl?: string;
+    onFallback?: (reason: string) => void;
+    onProgress?: (status: string) => void;
+}
+export interface PreparedTemplate {
+    install(targetDir: string): void;
+    cleanup(): void;
+}
+/**
+ * Check if a directory is empty.
+ */
+export declare function isDirectoryEmpty(dir: string): boolean;
+/**
+ * Downloads and validates the Primitive app template in a temporary staging
+ * directory. Nothing is written to the final target directory until install()
+ * is called.
+ */
+export declare function prepareTemplate(options?: PrepareTemplateOptions): Promise<PreparedTemplate>;
+export interface UpdateEnvResult {
+    envUpdated: boolean;
+    envProductionUpdated: boolean;
+}
+/** The backend a production build talks to, when the caller derived one. */
+export interface ProductionEnvTarget {
+    serverUrl: string;
+    appId: string;
+    appName?: string;
+}
+/**
+ * Updates .env and .env.production files with the app ID and server URLs.
+ * For .env, if it doesn't exist but .env.example does, copies from example first.
+ * Returns information about which files were updated.
+ *
+ * `production` names the backend/app pair a production build should talk to.
+ * Omit it and `.env.production` points at the hosted production server with
+ * this app id — the historical behavior, which is correct for an app created
+ * there and wrong for one created anywhere else, so composed runs derive the
+ * pair from the project's own environments and pass it in (#2890).
+ */
+export declare function updateEnvFile(targetDir: string, appId: string, serverUrl: string, appName?: string, production?: ProductionEnvTarget): UpdateEnvResult;
+/**
+ * Runs pnpm install in the target directory.
+ * Uses npx to ensure corepack/packageManager compatibility.
+ */
+export declare function runPnpmInstall(targetDir: string): Promise<void>;
+/**
+ * Checks if pnpm is installed globally.
+ */
+export declare function isPnpmInstalled(): Promise<boolean>;
+/**
+ * Installs pnpm globally using npm.
+ */
+export declare function installPnpmGlobally(): Promise<void>;
+/**
+ * Checks if the primitive CLI is installed and available in PATH.
+ * Checks for the `primitive` command directly, which covers installs via
+ * npm, pnpm, yarn, or any other package manager.
+ */
+export declare function isPrimitiveCliInstalled(): Promise<boolean>;
+export declare function gitInitRepo(targetDir: string): Promise<void>;
+export declare function gitInitialCommit(targetDir: string): Promise<void>;
+/**
+ * Checks whether a TCP port is currently in use on localhost.
+ * Tries both IPv4 (127.0.0.1) and IPv6 (::1) since a server may only
+ * bind to one address family.
+ */
+export declare function isPortFree(port: number): Promise<boolean>;
+/**
+ * Pins `server.port` in the source of a vite config. Returns the patched
+ * source, or null when the config's shape is one we can't patch — the caller
+ * must not claim success in that case.
+ *
+ * Exported for tests, which pin this against the real shipped template.
+ */
+export declare function patchViteConfigPort(content: string, port: number): string | null;
+/**
+ * Pins the dev server port in vite.config.{ts,js,mts,mjs} by injecting or
+ * updating the `server.port` field. Returns true only if a config file was
+ * found *and* actually rewritten.
+ */
+export declare function updateViteConfig(targetDir: string, port: number): boolean;
+/**
+ * Updates port-sensitive env vars (VITE_OAUTH_REDIRECT_URI, VITE_BASE_URL)
+ * in the project's .env file to point at the given localhost port.
+ */
+export declare function updateEnvPort(targetDir: string, port: number): void;
+/**
+ * Starting from `startPort` (default 5173), finds the first free port and
+ * returns which ports were already occupied and which port vite will bind to.
+ * `exhausted` is true when all checked ports were occupied and the returned
+ * port is a best-guess beyond the checked range.
+ */
+export declare function findDevPort(startPort?: number, maxChecks?: number): Promise<{
+    availablePort: number;
+    takenPorts: number[];
+    exhausted: boolean;
+}>;
+export { IOS_TEMPLATE_URL };
+/**
+ * Updates primitive.json in the iOS template with app ID, server URL, and app name.
+ * Replaces __PRIMITIVE_*__ placeholder values.
+ * Returns true if the file was found and updated.
+ */
+export declare function updatePrimitiveJson(targetDir: string, appId: string, serverUrl: string, appName?: string): boolean;
+export interface PrimitiveJsonResult {
+    /**
+     * - `generated` — the template's resolve script wrote it from
+     *   `primitive/config.json` (a current template).
+     * - `failed`    — that script ran and errored; `detail` carries its output.
+     * - `filled`    — an older template's tracked file had its placeholders
+     *   substituted.
+     * - `missing`   — neither; the caller warns.
+     */
+    outcome: "generated" | "failed" | "filled" | "missing";
+    detail?: string;
+}
+/**
+ * Gives an Apple scaffold a working `primitive.json`.
+ *
+ * In a current template that file is a BUILD PRODUCT generated from the
+ * Primitive environment in `primitive/config.json` (#2873) — the one place
+ * the app ID and server URL are typed. `init` has just scaffolded that config,
+ * so running the template's own resolve script here means the scaffold has a
+ * `primitive.json` immediately rather than only after its first build, and
+ * there is exactly one implementation of the resolution.
+ *
+ * A template that predates the change has no such script and ships a tracked
+ * file with `__PRIMITIVE_*__` placeholders instead; filling those in keeps a
+ * new CLI working against an old template.
+ */
+export declare function configurePrimitiveJson(targetDir: string, appId: string, serverUrl: string, appName?: string, options?: {
+    /**
+     * The environment this run resolved, when it resolved one explicitly —
+     * `primitive -e <name> init` adopting an existing app, say. The script
+     * applies the same precedence on its own, but from the machine's point of
+     * view: without being told, it would configure the client for this
+     * machine's selection or the committed default while the run reported
+     * another app.
+     */
+    environmentName?: string;
+}): PrimitiveJsonResult;
+/**
+ * Checks if Xcode command-line tools are installed.
+ */
+export declare function isXcodeInstalled(): Promise<boolean>;
+/**
+ * Runs `swift package resolve` in the target directory to download SPM dependencies.
+ */
+export declare function runSwiftPackageResolve(targetDir: string): Promise<void>;
+/**
+ * Installs the primitive CLI (primitive-admin) globally, using whichever
+ * package manager already owns a global copy — pnpm by default.
+ */
+export declare function installPrimitiveCli(): Promise<void>;