primitive-admin 1.1.0-alpha.4 → 1.1.0-alpha.40

package/dist/src/lib/sync-paths.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Sync data path resolution.
+ *
+ * Per issue #373, sync state is scoped by environment AND by app:
+ *
+ *   <projectRoot>/.primitive/sync/<env>/<appId>/
+ *
+ * This ensures that switching environments (dev -> prod) or apps never
+ * clobbers sync state from another slot. Push to dev and then to prod
+ * see independent "last synced" pointers, so prod won't falsely believe
+ * dev's changes are already in sync.
+ *
+ * When the user still passes `--dir <path>` (the legacy flag) we honor
+ * it and store sync state inside that directory, same as before. This
+ * keeps pre-project-config workflows working.
+ */
+export interface ResolveSyncDirOptions {
+    /** The resolved app ID for this sync operation. */
+    appId: string;
+    /**
+     * If the user passed `--dir <path>` on the command line, forward it
+     * here. Explicit user input always wins.
+     */
+    userDir?: string;
+}
+/**
+ * Returns the directory that should hold TOML files + sync state for the
+ * current sync operation.
+ *
+ * Resolution order:
+ *   1. If userDir is set, return it as-is (legacy behavior).
+ *   2. If we're in project mode, return
+ *      <projectRoot>/.primitive/sync/<env>/<appId>
+ *   3. Otherwise fall back to "./config" (the old default).
+ */
+export declare function resolveSyncDir(options: ResolveSyncDirOptions): string;
+/**
+ * Returns the snapshot-backups root for the slot a given sync operation
+ * belongs to (issue #578, Phase 1). Snapshots reuse the SAME resolution chain
+ * as `resolveSyncDir` (the resolved `ResolvedEnvironment` + `safeEnv()`), so
+ * the backup tree can never drift from the live sync tree — there is no
+ * parallel `{projectRoot, env, appId}` mini-model.
+ *
+ * Resolution order mirrors `resolveSyncDir`:
+ *   1. If userDir (legacy `--dir`) is set, snapshots live in a sibling
+ *      `<userDir>/.snapshots/` so revert works without a project root
+ *      (Fork 4 — designed explicitly).
+ *   2. In project mode, the project sibling
+ *      `<projectRoot>/.primitive/sync-backups/<env>/<appId>/`.
+ *   3. Otherwise (bare `./config` legacy default), `./config-snapshots`.
+ */
+export declare function resolveSnapshotsRoot(options: ResolveSyncDirOptions): string;
+export declare function assertSafePathComponent(value: string, label: string): void;
+/**
+ * Returns true if the path we'd use for sync data is the auto-resolved
+ * project-mode path (vs. a user-supplied --dir).
+ */
+export declare function isAutoResolvedSyncDir(userDir: string | undefined): boolean;
+/**
+ * Ensures the sync directory exists, creating it (and parents) if
+ * necessary. Returns the path.
+ */
+export declare function ensureSyncDir(options: ResolveSyncDirOptions): string;
+/**
+ * Checks whether an old-style sync state file exists at `./config/.primitive-sync.json`
+ * (the pre-project-config default path). Returns a warning message if found and
+ * the current operation is using a different (project-mode) path, or null otherwise.
+ *
+ * Callers can display this once at the start of sync commands so users know
+ * their old sync data won't be picked up automatically.
+ */
+export declare function checkLegacySyncMigration(currentSyncDir: string): string | null;

package/dist/src/lib/sync-paths.js

@@ -0,0 +1,130 @@
+/**
+ * Sync data path resolution.
+ *
+ * Per issue #373, sync state is scoped by environment AND by app:
+ *
+ *   <projectRoot>/.primitive/sync/<env>/<appId>/
+ *
+ * This ensures that switching environments (dev -> prod) or apps never
+ * clobbers sync state from another slot. Push to dev and then to prod
+ * see independent "last synced" pointers, so prod won't falsely believe
+ * dev's changes are already in sync.
+ *
+ * When the user still passes `--dir <path>` (the legacy flag) we honor
+ * it and store sync state inside that directory, same as before. This
+ * keeps pre-project-config workflows working.
+ */
+import { existsSync, mkdirSync } from "fs";
+import { join } from "path";
+import { getCurrentEnvironment } from "./env-resolver.js";
+/**
+ * Returns the directory that should hold TOML files + sync state for the
+ * current sync operation.
+ *
+ * Resolution order:
+ *   1. If userDir is set, return it as-is (legacy behavior).
+ *   2. If we're in project mode, return
+ *      <projectRoot>/.primitive/sync/<env>/<appId>
+ *   3. Otherwise fall back to "./config" (the old default).
+ */
+export function resolveSyncDir(options) {
+    if (options.userDir)
+        return options.userDir;
+    const env = safeEnv();
+    if (env) {
+        // Defence-in-depth: appId is expected to be a ULID from the server, but
+        // we must never trust it blindly when building file-system paths. Reject
+        // anything that contains path separators or `..` sequences before
+        // joining it into <projectRoot>/.primitive/sync/...
+        assertSafePathComponent(options.appId, "appId");
+        return join(env.projectRoot, ".primitive", "sync", env.name, options.appId);
+    }
+    return "./config";
+}
+/**
+ * Returns the snapshot-backups root for the slot a given sync operation
+ * belongs to (issue #578, Phase 1). Snapshots reuse the SAME resolution chain
+ * as `resolveSyncDir` (the resolved `ResolvedEnvironment` + `safeEnv()`), so
+ * the backup tree can never drift from the live sync tree — there is no
+ * parallel `{projectRoot, env, appId}` mini-model.
+ *
+ * Resolution order mirrors `resolveSyncDir`:
+ *   1. If userDir (legacy `--dir`) is set, snapshots live in a sibling
+ *      `<userDir>/.snapshots/` so revert works without a project root
+ *      (Fork 4 — designed explicitly).
+ *   2. In project mode, the project sibling
+ *      `<projectRoot>/.primitive/sync-backups/<env>/<appId>/`.
+ *   3. Otherwise (bare `./config` legacy default), `./config-snapshots`.
+ */
+export function resolveSnapshotsRoot(options) {
+    if (options.userDir) {
+        return join(options.userDir, ".snapshots");
+    }
+    const env = safeEnv();
+    if (env) {
+        // Same defence-in-depth as resolveSyncDir: never trust appId blindly when
+        // building a file-system path.
+        assertSafePathComponent(options.appId, "appId");
+        return join(env.projectRoot, ".primitive", "sync-backups", env.name, options.appId);
+    }
+    return "./config-snapshots";
+}
+export function assertSafePathComponent(value, label) {
+    if (typeof value !== "string" ||
+        value.length === 0 ||
+        /[\\/]/.test(value) ||
+        value.includes("..") ||
+        value === "." ||
+        value === "") {
+        throw new Error(`Invalid ${label} for file path: ${value}`);
+    }
+}
+/**
+ * Returns true if the path we'd use for sync data is the auto-resolved
+ * project-mode path (vs. a user-supplied --dir).
+ */
+export function isAutoResolvedSyncDir(userDir) {
+    if (userDir)
+        return false;
+    return safeEnv() !== null;
+}
+/**
+ * Ensures the sync directory exists, creating it (and parents) if
+ * necessary. Returns the path.
+ */
+export function ensureSyncDir(options) {
+    const dir = resolveSyncDir(options);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    return dir;
+}
+function safeEnv() {
+    try {
+        return getCurrentEnvironment();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Checks whether an old-style sync state file exists at `./config/.primitive-sync.json`
+ * (the pre-project-config default path). Returns a warning message if found and
+ * the current operation is using a different (project-mode) path, or null otherwise.
+ *
+ * Callers can display this once at the start of sync commands so users know
+ * their old sync data won't be picked up automatically.
+ */
+export function checkLegacySyncMigration(currentSyncDir) {
+    const legacySync = join(".", "config", ".primitive-sync.json");
+    if (!existsSync(legacySync))
+        return null;
+    // Only warn if the resolved dir is different from the legacy default.
+    const legacyDir = join(".", "config");
+    if (currentSyncDir === legacyDir)
+        return null;
+    return (`Detected old sync state at ./config/.primitive-sync.json. ` +
+        `Sync data now lives at ${currentSyncDir}. ` +
+        `Run 'primitive sync pull' to re-sync into the new location.`);
+}
+//# sourceMappingURL=sync-paths.js.map

package/dist/src/lib/sync-paths.js.map

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

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

@@ -0,0 +1,97 @@
+declare const IOS_TEMPLATE_URL = "https://api.github.com/repos/Primitive-Labs/primitive-ios-template/tarball/main";
+export interface PrepareTemplateOptions {
+    templateUrl?: string;
+    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;
+}
+/**
+ * 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.
+ */
+export declare function updateEnvFile(targetDir: string, appId: string, serverUrl: string, appName?: string): 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 the dev server port in vite.config.{ts,js,mts,mjs} by injecting or
+ * updating the `server.port` field. Returns true if a config file was found
+ * and patched.
+ */
+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;
+/**
+ * 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 npm.
+ */
+export declare function installPrimitiveCli(): Promise<void>;