@kokimoki/kit 1.6.7 → 1.8.0

package/README.md

@@ -0,0 +1,76 @@
+# @kokimoki/kit
+
+Vite plugin and development tools for building Kokimoki apps.
+
+## Installation
+
+```bash
+npm install @kokimoki/kit
+```
+
+## Quick Start
+
+Add the plugin to your `vite.config.ts`:
+
+```typescript
+import { defineConfig } from "vite";
+import { kokimokiKitPlugin } from "@kokimoki/kit";
+import { z } from "@kokimoki/kit";
+
+export default defineConfig({
+  plugins: [
+    kokimokiKitPlugin({
+      conceptId: "your-concept-id",
+      deployCodes: [
+        {
+          name: "default",
+          description: "Default configuration",
+          clientContext: {},
+        },
+      ],
+      schema: z.object({
+        title: z.string(),
+        maxPlayers: z.number(),
+      }),
+      stores: [
+        { pattern: "game", schema: z.object({ status: z.string() }) },
+        {
+          pattern: "player-*",
+          schema: z.object({ name: z.string() }),
+          local: true,
+        },
+      ],
+      i18nPath: "./src/i18n",
+      i18nPrimaryLng: "en",
+      devView: [
+        [{ label: "host", clientContext: { mode: "host" } }],
+        [
+          { label: "player1", clientContext: { mode: "player" } },
+          { label: "player2", clientContext: { mode: "player" } },
+        ],
+      ],
+    }),
+  ],
+});
+```
+
+## Features
+
+- **Vite Plugin** - Integrates Kokimoki into your Vite build
+- **Dev Frame** - Multi-window development view for testing different player modes
+- **Schema Validation** - Zod-based validation for stores and project config
+- **i18n Sync** - Automatic synchronization of translations during development
+- **Style Preprocessing** - Theme color processing for CSS variables
+
+## Documentation
+
+See the [docs](./docs/) folder for detailed instructions:
+
+| File                                                                | Description                    |
+| ------------------------------------------------------------------- | ------------------------------ |
+| [kokimoki-kit.instructions.md](./docs/kokimoki-kit.instructions.md) | Plugin configuration and usage |
+
+## Related Packages
+
+- **@kokimoki/app** - Core SDK for runtime (stores, transactions, AI, etc.)
+- **@kokimoki/cli** - CLI for project creation and deployment

package/dist/api.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Kokimoki API utilities
+ * Shared between @kokimoki/cli and @kokimoki/kit
+ */
+import { Organization } from "./credentials";
+export declare const DEFAULT_ENDPOINT = "https://api.kokimoki.com";
+export interface KokimokiApiOptions {
+    endpoint: string;
+    apiKey: string;
+}
+export interface CreateConceptRequest {
+    packageName: string;
+    name: string;
+}
+export interface CreateConceptResponse {
+    id: string;
+}
+export interface CreateBuildRequest {
+    projectId: string;
+    schema: string;
+    deployCodes?: {
+        name: string;
+        description: string;
+        clientContext: any;
+    }[];
+    defaultStyle?: string;
+    defaultConfig?: string;
+    version: string;
+    changelog?: string;
+    i18n?: {
+        path: string;
+        primaryLng: string;
+        namespaces: string[];
+        languages: string[];
+    };
+}
+export interface CreateBuildResponse {
+    id: string;
+    publicPath: string;
+}
+/**
+ * Create a new concept via the Kokimoki API
+ */
+export declare function createConcept(options: KokimokiApiOptions, request: CreateConceptRequest): Promise<CreateConceptResponse>;
+/**
+ * Get organization details via the Kokimoki API
+ * Used for authentication validation
+ */
+export declare function getOrganization(endpoint: string, apiKey: string): Promise<Organization>;
+/**
+ * Get the organization that owns a concept (by concept ID)
+ */
+export declare function getConceptOrganization(endpoint: string, conceptId: string): Promise<Organization>;
+/**
+ * Create a new build via the Kokimoki API
+ */
+export declare function createBuild(options: KokimokiApiOptions, request: CreateBuildRequest, cliVersion?: string): Promise<CreateBuildResponse>;
+/**
+ * Get the deploy URL for a build
+ */
+export declare function getDeployUrl(endpoint: string, apiKey: string, buildId: string): Promise<{
+    url: string;
+}>;

package/dist/api.js

@@ -0,0 +1,95 @@
+"use strict";
+/**
+ * Kokimoki API utilities
+ * Shared between @kokimoki/cli and @kokimoki/kit
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDeployUrl = exports.createBuild = exports.getConceptOrganization = exports.getOrganization = exports.createConcept = exports.DEFAULT_ENDPOINT = void 0;
+exports.DEFAULT_ENDPOINT = "https://api.kokimoki.com";
+/**
+ * Make a request to the Kokimoki API
+ */
+async function kokimokiApiRequest(path, options, init) {
+    const url = `${options.endpoint}${path}`;
+    const res = await fetch(url, {
+        ...init,
+        headers: {
+            Authorization: options.apiKey,
+            "Content-Type": "application/json",
+            ...init?.headers,
+        },
+    });
+    if (!res.ok) {
+        const errorText = await res.text();
+        throw new Error(`Kokimoki API request failed: ${res.status} ${res.statusText} - ${errorText}`);
+    }
+    return await res.json();
+}
+/**
+ * Create a new concept via the Kokimoki API
+ */
+async function createConcept(options, request) {
+    return kokimokiApiRequest("/concepts", options, {
+        method: "POST",
+        body: JSON.stringify(request),
+    });
+}
+exports.createConcept = createConcept;
+/**
+ * Get organization details via the Kokimoki API
+ * Used for authentication validation
+ */
+async function getOrganization(endpoint, apiKey) {
+    return kokimokiApiRequest("/auth", { endpoint, apiKey }, { method: "GET" });
+}
+exports.getOrganization = getOrganization;
+/**
+ * Get the organization that owns a concept (by concept ID)
+ */
+async function getConceptOrganization(endpoint, conceptId) {
+    const url = `${endpoint}/concepts/${conceptId}/organization`;
+    const res = await fetch(url, {
+        method: "GET",
+        headers: {
+            "Content-Type": "application/json",
+        },
+    });
+    if (!res.ok) {
+        const errorData = await res.json().catch(() => ({}));
+        throw new Error(errorData.message || `Failed to get concept organization: ${res.status}`);
+    }
+    return await res.json();
+}
+exports.getConceptOrganization = getConceptOrganization;
+/**
+ * Create a new build via the Kokimoki API
+ */
+async function createBuild(options, request, cliVersion) {
+    return kokimokiApiRequest("/builds", options, {
+        method: "POST",
+        headers: {
+            "X-KM-CLI-Version": cliVersion || "",
+        },
+        body: JSON.stringify(request),
+    });
+}
+exports.createBuild = createBuild;
+/**
+ * Get the deploy URL for a build
+ */
+async function getDeployUrl(endpoint, apiKey, buildId) {
+    const url = `${endpoint}/deploy-urls/builds/${buildId}`;
+    const res = await fetch(url, {
+        method: "GET",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: apiKey,
+        },
+    });
+    if (!res.ok) {
+        const errorData = await res.json().catch(() => ({}));
+        throw new Error(errorData.message || `Failed to get deploy URL: ${res.status}`);
+    }
+    return await res.json();
+}
+exports.getDeployUrl = getDeployUrl;

package/dist/credentials.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Credentials management for Kokimoki CLI and Kit
+ * Shared between @kokimoki/cli and @kokimoki/kit
+ */
+export interface Credentials {
+    apiKeys: {
+        [organizationId: string]: string;
+    };
+}
+export interface Organization {
+    id: string;
+    name: string;
+}
+/**
+ * Get the path to the global credentials file (~/.kokimoki)
+ */
+export declare function getCredentialsPath(): string;
+/**
+ * Read credentials from the ~/.kokimoki file
+ */
+export declare function readCredentials(): Promise<Credentials | null>;
+/**
+ * Write credentials to the ~/.kokimoki file
+ */
+export declare function writeCredentials(credentials: Credentials): Promise<void>;

package/dist/credentials.js

@@ -0,0 +1,45 @@
+"use strict";
+/**
+ * Credentials management for Kokimoki CLI and Kit
+ * Shared between @kokimoki/cli and @kokimoki/kit
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeCredentials = exports.readCredentials = exports.getCredentialsPath = void 0;
+const promises_1 = __importDefault(require("fs/promises"));
+const os_1 = require("os");
+const path_1 = __importDefault(require("path"));
+/**
+ * Get the path to the global credentials file (~/.kokimoki)
+ */
+function getCredentialsPath() {
+    return path_1.default.join((0, os_1.homedir)(), ".kokimoki");
+}
+exports.getCredentialsPath = getCredentialsPath;
+/**
+ * Read credentials from the ~/.kokimoki file
+ */
+async function readCredentials() {
+    try {
+        const credentialsPath = getCredentialsPath();
+        const credentialsJson = await promises_1.default.readFile(credentialsPath, "utf-8");
+        return JSON.parse(credentialsJson);
+    }
+    catch (e) {
+        if (e?.code === "ENOENT") {
+            return null;
+        }
+        throw e;
+    }
+}
+exports.readCredentials = readCredentials;
+/**
+ * Write credentials to the ~/.kokimoki file
+ */
+async function writeCredentials(credentials) {
+    const credentialsPath = getCredentialsPath();
+    await promises_1.default.writeFile(credentialsPath, JSON.stringify(credentials, null, 2));
+}
+exports.writeCredentials = writeCredentials;

package/dist/dev-app.d.ts

@@ -0,0 +1,57 @@
+import { Credentials, Organization } from "./credentials";
+export type { Credentials, Organization };
+export interface DevAppConfig {
+    conceptId: string;
+    endpoint?: string;
+}
+export interface DevAppError {
+    code: "CONCEPT_NOT_FOUND" | "NO_CREDENTIALS" | "DEV_APP_INIT_FAILED";
+    message: string;
+}
+export interface DevAppResult {
+    appId: string;
+    buildUrl?: string;
+    organization?: Organization;
+    error?: DevAppError;
+}
+/**
+ * Delete the app ID file from .kokimoki/app-id
+ */
+export declare function deleteAppId(): Promise<void>;
+/**
+ * Set i18n metadata for a dev app
+ */
+export declare function setDevAppI18n(endpoint: string, apiKey: string, appId: string, i18nMeta: {
+    path: string;
+    primaryLng: string;
+    namespaces: string[];
+}): Promise<void>;
+/**
+ * Set translations for a specific language and namespace in a dev app
+ */
+export declare function setDevAppTranslation(endpoint: string, apiKey: string, appId: string, lng: string, namespace: string, translations: Record<string, unknown>): Promise<void>;
+/**
+ * Compute a hash of the stores configuration
+ */
+export declare function computeStoresHash(stores: unknown): string;
+/**
+ * Read the stored stores hash from .kokimoki/stores-hash
+ */
+export declare function readStoresHash(): Promise<string | null>;
+/**
+ * Write the stores hash to .kokimoki/stores-hash
+ */
+export declare function writeStoresHash(hash: string): Promise<void>;
+/**
+ * Get or create a dev app for local development.
+ *
+ * This function will:
+ * 1. Verify the concept ID and get the organization it belongs to
+ * 2. Read credentials from ~/.kokimoki
+ * 3. If an app ID exists locally, verify it with the API
+ * 4. If no app ID exists or verification fails, initialize a new dev app
+ * 5. Store the app ID in .kokimoki/app-id
+ *
+ * If credentials are not available, falls back to generating a local-only ObjectId.
+ */
+export declare function getOrCreateDevApp(config: DevAppConfig): Promise<DevAppResult>;

package/dist/dev-app.js

@@ -0,0 +1,272 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getOrCreateDevApp = exports.writeStoresHash = exports.readStoresHash = exports.computeStoresHash = exports.setDevAppTranslation = exports.setDevAppI18n = exports.deleteAppId = void 0;
+const crypto_1 = __importDefault(require("crypto"));
+const bson_objectid_1 = __importDefault(require("bson-objectid"));
+const promises_1 = __importDefault(require("fs/promises"));
+const path_1 = __importDefault(require("path"));
+const api_1 = require("./api");
+const credentials_1 = require("./credentials");
+const KOKIMOKI_DIR = ".kokimoki";
+const APP_ID_FILE = "app-id";
+const STORES_HASH_FILE = "stores-hash";
+/**
+ * Initialize a new dev app via the Kokimoki API
+ */
+async function initializeDevApp(endpoint, apiKey, conceptId) {
+    const url = `${endpoint}/dev-apps`;
+    const res = await fetch(url, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: apiKey,
+        },
+        body: JSON.stringify({ conceptId }),
+    });
+    if (!res.ok) {
+        const errorData = await res.json().catch(() => ({}));
+        throw new Error(errorData.message || `Failed to initialize dev app: ${res.status}`);
+    }
+    const data = await res.json();
+    return { appId: data.appId, buildUrl: data.buildUrl };
+}
+/**
+ * Verify an existing dev app ID via the Kokimoki API
+ * Returns buildUrl if valid, null if invalid
+ */
+async function verifyDevApp(endpoint, apiKey, appId, conceptId) {
+    const url = `${endpoint}/dev-apps/${appId}/verify`;
+    const res = await fetch(url, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: apiKey,
+        },
+        body: JSON.stringify({ conceptId }),
+    });
+    if (!res.ok) {
+        // If verification fails, the app ID may be invalid or belong to a different concept
+        return null;
+    }
+    const data = await res.json();
+    return data.valid === true ? data.buildUrl : null;
+}
+/**
+ * Ensure the .kokimoki directory exists
+ */
+async function ensureKokimokiDir() {
+    try {
+        await promises_1.default.mkdir(KOKIMOKI_DIR);
+    }
+    catch (e) {
+        if (e?.code !== "EEXIST") {
+            throw e;
+        }
+    }
+}
+/**
+ * Read the local app ID from .kokimoki/app-id
+ */
+async function readLocalAppId() {
+    try {
+        const appId = await promises_1.default.readFile(path_1.default.join(KOKIMOKI_DIR, APP_ID_FILE), "utf8");
+        return appId.trim() || null;
+    }
+    catch (e) {
+        if (e?.code === "ENOENT") {
+            return null;
+        }
+        throw e;
+    }
+}
+/**
+ * Write the app ID to .kokimoki/app-id
+ */
+async function writeLocalAppId(appId) {
+    await ensureKokimokiDir();
+    await promises_1.default.writeFile(path_1.default.join(KOKIMOKI_DIR, APP_ID_FILE), appId);
+}
+/**
+ * Delete the app ID file from .kokimoki/app-id
+ */
+async function deleteAppId() {
+    try {
+        await promises_1.default.unlink(path_1.default.join(KOKIMOKI_DIR, APP_ID_FILE));
+    }
+    catch (e) {
+        if (e?.code !== "ENOENT") {
+            throw e;
+        }
+    }
+}
+exports.deleteAppId = deleteAppId;
+/**
+ * Set i18n metadata for a dev app
+ */
+async function setDevAppI18n(endpoint, apiKey, appId, i18nMeta) {
+    const url = `${endpoint}/dev-apps/${appId}/i18n`;
+    const res = await fetch(url, {
+        method: "PUT",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: apiKey,
+        },
+        body: JSON.stringify(i18nMeta),
+    });
+    if (!res.ok) {
+        const errorText = await res.text().catch(() => "");
+        throw new Error(`Failed to set dev app i18n: ${res.status} ${errorText}`);
+    }
+}
+exports.setDevAppI18n = setDevAppI18n;
+/**
+ * Set translations for a specific language and namespace in a dev app
+ */
+async function setDevAppTranslation(endpoint, apiKey, appId, lng, namespace, translations) {
+    const url = `${endpoint}/dev-apps/${appId}/translations/${lng}/${namespace}`;
+    const res = await fetch(url, {
+        method: "PUT",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: apiKey,
+        },
+        body: JSON.stringify(translations),
+    });
+    if (!res.ok) {
+        const errorText = await res.text().catch(() => "");
+        throw new Error(`Failed to set dev app translation: ${res.status} ${errorText}`);
+    }
+}
+exports.setDevAppTranslation = setDevAppTranslation;
+/**
+ * Compute a hash of the stores configuration
+ */
+function computeStoresHash(stores) {
+    const content = JSON.stringify(stores ?? []);
+    return crypto_1.default.createHash("sha256").update(content).digest("hex").slice(0, 16);
+}
+exports.computeStoresHash = computeStoresHash;
+/**
+ * Read the stored stores hash from .kokimoki/stores-hash
+ */
+async function readStoresHash() {
+    try {
+        const hash = await promises_1.default.readFile(path_1.default.join(KOKIMOKI_DIR, STORES_HASH_FILE), "utf8");
+        return hash.trim() || null;
+    }
+    catch (e) {
+        if (e?.code === "ENOENT") {
+            return null;
+        }
+        throw e;
+    }
+}
+exports.readStoresHash = readStoresHash;
+/**
+ * Write the stores hash to .kokimoki/stores-hash
+ */
+async function writeStoresHash(hash) {
+    await ensureKokimokiDir();
+    await promises_1.default.writeFile(path_1.default.join(KOKIMOKI_DIR, STORES_HASH_FILE), hash);
+}
+exports.writeStoresHash = writeStoresHash;
+/**
+ * Get or create a dev app for local development.
+ *
+ * This function will:
+ * 1. Verify the concept ID and get the organization it belongs to
+ * 2. Read credentials from ~/.kokimoki
+ * 3. If an app ID exists locally, verify it with the API
+ * 4. If no app ID exists or verification fails, initialize a new dev app
+ * 5. Store the app ID in .kokimoki/app-id
+ *
+ * If credentials are not available, falls back to generating a local-only ObjectId.
+ */
+async function getOrCreateDevApp(config) {
+    const endpoint = config.endpoint ?? api_1.DEFAULT_ENDPOINT;
+    await ensureKokimokiDir();
+    // Try to read existing app ID
+    let appId = await readLocalAppId();
+    // Try to verify concept and get organization
+    let organization;
+    try {
+        organization = await (0, api_1.getConceptOrganization)(endpoint, config.conceptId);
+    }
+    catch (e) {
+        const errorMessage = e instanceof Error ? e.message : "unknown error";
+        console.warn(`[kokimoki-kit] Could not verify concept: ${errorMessage}`);
+        // Fall back to local-only mode but report error
+        if (!appId) {
+            appId = new bson_objectid_1.default().toHexString();
+            await writeLocalAppId(appId);
+        }
+        return {
+            appId,
+            error: {
+                code: "CONCEPT_NOT_FOUND",
+                message: `Could not verify concept "${config.conceptId}": ${errorMessage}. Make sure the conceptId in your vite.config is correct.`,
+            },
+        };
+    }
+    // Try to read credentials
+    const credentials = await (0, credentials_1.readCredentials)();
+    const apiKey = credentials?.apiKeys?.[organization.id];
+    if (!apiKey) {
+        const errorMessage = `No credentials found for organization ${organization.name} (${organization.id}). Run "kokimoki login" to authenticate.`;
+        console.warn(`[kokimoki-kit] ${errorMessage}`);
+        // Fall back to local-only mode but report error
+        if (!appId) {
+            appId = new bson_objectid_1.default().toHexString();
+            await writeLocalAppId(appId);
+        }
+        return {
+            appId,
+            organization,
+            error: {
+                code: "NO_CREDENTIALS",
+                message: errorMessage,
+            },
+        };
+    }
+    // If we have an existing app ID, verify it
+    if (appId) {
+        try {
+            const buildUrl = await verifyDevApp(endpoint, apiKey, appId, config.conceptId);
+            if (buildUrl) {
+                return { appId, buildUrl, organization };
+            }
+            console.warn(`[kokimoki-kit] Existing dev app ID is invalid or belongs to a different concept. Creating new one.`);
+        }
+        catch (e) {
+            console.warn(`[kokimoki-kit] Could not verify dev app: ${e instanceof Error ? e.message : "unknown error"}`);
+        }
+    }
+    // Initialize a new dev app
+    try {
+        const { appId: newAppId, buildUrl } = await initializeDevApp(endpoint, apiKey, config.conceptId);
+        appId = newAppId;
+        await writeLocalAppId(appId);
+        return { appId, buildUrl, organization };
+    }
+    catch (e) {
+        const errorMessage = e instanceof Error ? e.message : "unknown error";
+        console.warn(`[kokimoki-kit] Could not initialize dev app: ${errorMessage}`);
+        // Fall back to local-only mode but report error
+        if (!appId) {
+            appId = new bson_objectid_1.default().toHexString();
+            await writeLocalAppId(appId);
+        }
+        return {
+            appId,
+            organization,
+            error: {
+                code: "DEV_APP_INIT_FAILED",
+                message: `Could not initialize dev app: ${errorMessage}`,
+            },
+        };
+    }
+}
+exports.getOrCreateDevApp = getOrCreateDevApp;

package/dist/dev-frame/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Dev frame module - provides a multi-window development view
+ * for testing host, presenter, and player modes simultaneously
+ */
+export { renderDevFrame, type DevFrameCell, type DevFrameConfig, } from "./render-dev-frame";

package/dist/dev-frame/index.js

@@ -0,0 +1,9 @@
+"use strict";
+/**
+ * Dev frame module - provides a multi-window development view
+ * for testing host, presenter, and player modes simultaneously
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderDevFrame = void 0;
+var render_dev_frame_1 = require("./render-dev-frame");
+Object.defineProperty(exports, "renderDevFrame", { enumerable: true, get: function () { return render_dev_frame_1.renderDevFrame; } });

package/dist/dev-frame/render-dev-frame.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Renders the dev frame HTML page - a multi-window view for development
+ */
+export interface DevFrameCell {
+    /** Label shown in the frame header */
+    label: string;
+    /** Client context passed to the app */
+    clientContext: unknown;
+}
+export interface DevFrameConfig {
+    /** Title shown in browser tab */
+    title?: string;
+    /**
+     * App meta for SEO and social sharing. Title will be appended with " - Dev View".
+     */
+    appMeta?: {
+        lang?: string;
+        title?: string;
+        description?: string;
+        ogTitle?: string;
+        ogDescription?: string;
+        ogImage?: string;
+        favicon?: string;
+    };
+    /**
+     * Grid layout for the dev frame. Each inner array is a row,
+     * and each item in the row is a cell/frame.
+     *
+     * Example:
+     * ```
+     * [
+     *   [{ label: 'host', clientContext: {...} }, { label: 'presenter', clientContext: {...} }],
+     *   [{ label: 'player1', clientContext: {...} }, { label: 'player2', clientContext: {...} }]
+     * ]
+     * ```
+     */
+    rows: readonly (readonly DevFrameCell[])[];
+}
+/**
+ * Render the complete dev frame HTML page
+ */
+export declare function renderDevFrame(config: DevFrameConfig): string;