@nosto/nosto-cli 1.0.1

package/eslint.config.js

@@ -0,0 +1,36 @@
+import js from "@eslint/js"
+import { defineConfig } from "eslint/config"
+import eslintPluginPrettierRecommended from "eslint-plugin-prettier/recommended"
+import simpleImportSort from "eslint-plugin-simple-import-sort"
+import unusedImports from "eslint-plugin-unused-imports"
+import tseslint from "typescript-eslint"
+
+export default defineConfig([
+  {
+    files: ["**/*.ts"],
+    plugins: {
+      js,
+      "@typescript-eslint": tseslint.plugin
+    },
+    extends: ["js/recommended", ...tseslint.configs.recommended],
+    languageOptions: {
+      parser: tseslint.parser,
+      parserOptions: {
+        project: "./tsconfig.json"
+      }
+    }
+  },
+  {
+    plugins: {
+      "unused-imports": unusedImports,
+      "simple-import-sort": simpleImportSort
+    },
+    rules: {
+      "unused-imports/no-unused-imports": "error",
+      "simple-import-sort/imports": "error",
+      "simple-import-sort/exports": "error",
+      "no-restricted-imports": ["error", "node:test"]
+    }
+  },
+  eslintPluginPrettierRecommended
+])

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@nosto/nosto-cli",
+  "version": "1.0.1",
+  "main": "./src/index.ts",
+  "bin": {
+    "nosto": "./src/bootstrap.sh"
+  },
+  "author": "Nosto",
+  "type": "module",
+  "imports": {
+    "#*": "./src/*"
+  },
+  "exports": {
+    ".": "./src/exports.ts"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "license": "ISC",
+  "description": "",
+  "scripts": {
+    "lint": "eslint",
+    "lint:fix": "eslint --fix",
+    "prepare": "husky",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest run --coverage",
+    "type-check": "tsc --noEmit"
+  },
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "commander": "^14.0.1",
+    "esbuild": "^0.25.10",
+    "ignore": "^7.0.5",
+    "open": "^10.2.0",
+    "ky": "^1.11.0",
+    "preact": "^10.27.2",
+    "zod": "^4.1.11"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^20.1.0",
+    "@commitlint/config-conventional": "^20.0.0",
+    "@eslint/js": "^9.37.0",
+    "@types/node": "^24.7.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "@vitest/ui": "^3.2.4",
+    "eslint": "^9.37.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.4",
+    "eslint-plugin-simple-import-sort": "^12.1.1",
+    "eslint-plugin-unused-imports": "^4.2.0",
+    "husky": "^9.1.7",
+    "memfs": "^4.48.1",
+    "msw": "^2.11.3",
+    "prettier": "^3.6.2",
+    "typescript-eslint": "^8.45.0",
+    "vitest": "^3.2.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/api/library/fetchLibraryFile.ts

@@ -0,0 +1,18 @@
+import ky from "ky"
+import z from "zod"
+
+import { cleanUrl, getJsonHeaders } from "#api/utils.ts"
+import { getCachedConfig } from "#config/config.ts"
+
+const FetchSourceFileSchema = z.string()
+
+export async function fetchLibraryFile(path: string) {
+  const config = getCachedConfig()
+  const url = `${config.libraryUrl}/${cleanUrl(path)}`
+
+  const response = await ky.get(url.toString(), {
+    headers: getJsonHeaders()
+  })
+  const data = FetchSourceFileSchema.parse(await response.text())
+  return data
+}

package/src/api/retry.ts

@@ -0,0 +1,28 @@
+import chalk from "chalk"
+
+import { Logger } from "#console/logger.ts"
+
+const MAX_RETRIES = 3
+const INITIAL_RETRY_DELAY = 1000 // 1 second
+
+export async function fetchWithRetry(
+  apiFunction: (filePath: string) => Promise<string>,
+  filePath: string,
+  retryCount = 0
+): Promise<string> {
+  try {
+    return await apiFunction(filePath)
+  } catch (error: unknown) {
+    if (retryCount >= MAX_RETRIES) {
+      const errorMessage = error instanceof Error ? error.message : String(error)
+      Logger.error(`${chalk.red("✗")} ${chalk.cyan(filePath)}: ${errorMessage}`)
+      throw new Error(`Failed to fetch ${filePath} after ${MAX_RETRIES} retries: ${errorMessage}`)
+    }
+    const delay = INITIAL_RETRY_DELAY * Math.pow(2, retryCount)
+    Logger.warn(
+      `${chalk.yellow("⟳")} Failed to fetch ${chalk.cyan(filePath)}: Retrying in ${delay}ms (attempt ${retryCount + 1}/${MAX_RETRIES})`
+    )
+    await new Promise(resolve => setTimeout(resolve, delay))
+    return fetchWithRetry(apiFunction, filePath, retryCount + 1)
+  }
+}

package/src/api/source/fetchSourceFile.ts

@@ -0,0 +1,33 @@
+import ky from "ky"
+import z from "zod"
+
+import { getJsonHeaders, getSourceUrl } from "#api/utils.ts"
+
+const FetchSourceFileSchema = z.string()
+
+export async function fetchSourceFile(path: string) {
+  const response = await ky.get(getSourceUrl(`source/{env}/${path}`), {
+    headers: getJsonHeaders()
+  })
+  const data = FetchSourceFileSchema.parse(await response.text())
+  return data
+}
+
+const KyErrorSchema = z.object({
+  response: z.object({
+    status: z.number(),
+    statusText: z.string()
+  })
+})
+
+export async function fetchSourceFileIfExists(path: string) {
+  try {
+    return await fetchSourceFile(path)
+  } catch (error) {
+    const parsedError = KyErrorSchema.safeParse(error)
+    if (parsedError.success && parsedError.data.response.status === 404) {
+      return null
+    }
+    throw error
+  }
+}

package/src/api/source/listSourceFiles.ts

@@ -0,0 +1,13 @@
+import ky from "ky"
+
+import { getJsonHeaders, getSourceUrl } from "#api/utils.ts"
+
+import { ListSourceFilesSchema } from "./schema.ts"
+
+export async function listSourceFiles() {
+  const response = await ky.get(getSourceUrl("source/{env}"), {
+    headers: getJsonHeaders()
+  })
+  const files = ListSourceFilesSchema.parse(await response.json())
+  return files.filter(file => file.path)
+}

package/src/api/source/putSourceFile.ts

@@ -0,0 +1,14 @@
+import ky from "ky"
+
+import { getHeaders, getSourceUrl } from "#api/utils.ts"
+import { getCachedConfig } from "#config/config.ts"
+
+export async function putSourceFile(path: string, data: string) {
+  if (getCachedConfig().dryRun) {
+    return
+  }
+  await ky.put(getSourceUrl(`source/{env}/${path}`), {
+    headers: getHeaders(),
+    body: data
+  })
+}

package/src/api/source/schema.ts

@@ -0,0 +1,10 @@
+import z from "zod"
+
+export const ListSourceFilesSchema = z.array(
+  z.object({
+    path: z.string(),
+    size: z.number()
+  })
+)
+
+export const ListLibraryFilesSchema = ListSourceFilesSchema

package/src/api/utils.ts

@@ -0,0 +1,52 @@
+import { getCachedConfig } from "#config/config.ts"
+
+export function getSourceUrl(path: string) {
+  const config = getCachedConfig()
+  const merchant = config.merchant
+  const env = config.templatesEnv
+  const replacedPath = path.replace("{env}", env)
+  return `${config.apiUrl}/${merchant}/search-templates/${replacedPath}`
+}
+
+export function getHeaders() {
+  return new Headers({
+    "Content-Type": "application/octet-stream",
+    ...getAuthHeaders()
+  })
+}
+
+export function getJsonHeaders() {
+  return new Headers({
+    "Content-Type": "application/json",
+    ...getAuthHeaders()
+  })
+}
+
+type AuthHeaders =
+  | {
+      Authorization: string
+    }
+  | {
+      "X-Nosto-User": string
+      "X-Nosto-Token": string
+      "X-Nosto-Merchant": string
+    }
+
+function getAuthHeaders(): AuthHeaders {
+  const config = getCachedConfig()
+  if (config.apiKey) {
+    return {
+      Authorization: "Basic " + btoa(":" + config.apiKey)
+    }
+  }
+  return {
+    "X-Nosto-User": config.auth.user,
+    "X-Nosto-Token": config.auth.token,
+    "X-Nosto-Merchant": config.merchant
+  }
+}
+
+// Remove trailing and leading slashes
+export function cleanUrl(url: string) {
+  return url.replace(/^\/+|\/+$/g, "")
+}

package/src/bootstrap.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+
+# A more robust way to get the script directory that works with symlinks
+get_script_dir()
+{
+    local SOURCE_PATH="${BASH_SOURCE[0]}"
+    local SYMLINK_DIR
+    local SCRIPT_DIR
+    # Resolve symlinks recursively
+    while [ -L "$SOURCE_PATH" ]; do
+        # Get symlink directory
+        SYMLINK_DIR="$( cd -P "$( dirname "$SOURCE_PATH" )" >/dev/null 2>&1 && pwd )"
+        # Resolve symlink target (relative or absolute)
+        SOURCE_PATH="$(readlink "$SOURCE_PATH")"
+        # Check if candidate path is relative or absolute
+        if [[ $SOURCE_PATH != /* ]]; then
+            # Candidate path is relative, resolve to full path
+            SOURCE_PATH=$SYMLINK_DIR/$SOURCE_PATH
+        fi
+    done
+    # Get final script directory path from fully resolved source path
+    SCRIPT_DIR="$(cd -P "$( dirname "$SOURCE_PATH" )" >/dev/null 2>&1 && pwd)"
+    echo "$SCRIPT_DIR"
+}
+
+exec node --experimental-strip-types --disable-warning=ExperimentalWarning "$(get_script_dir)/index.ts" "$@"

package/src/commander.ts

@@ -0,0 +1,119 @@
+import { Command } from "commander"
+
+import { loadConfig } from "#config/config.ts"
+import { Logger } from "#console/logger.ts"
+import { withErrorHandler } from "#errors/withErrorHandler.ts"
+import { loginToPlaycart } from "#modules/login.ts"
+import { removeLoginCredentials } from "#modules/logout.ts"
+import { buildSearchTemplate } from "#modules/search-templates/build.ts"
+import { searchTemplateDevMode } from "#modules/search-templates/dev.ts"
+import { pullSearchTemplate } from "#modules/search-templates/pull.ts"
+import { pushSearchTemplate } from "#modules/search-templates/push.ts"
+import { printSetupHelp } from "#modules/setup.ts"
+import { printStatus } from "#modules/status.ts"
+import { withSafeEnvironment } from "#utils/withSafeEnvironment.ts"
+
+export async function runCLI(argv: string[]) {
+  const program = new Command()
+  program.name("nostocli").version("1.0.0").description("Nosto CLI tool. Use `nostocli setup` to get started.")
+
+  program
+    .command("login")
+    .description("Login with your Nosto account")
+    .option("--verbose", "set log level to debug")
+    .action(async options => {
+      await loadConfig({ options, allowIncomplete: true, projectPath: "." })
+      await withErrorHandler(async () => {
+        await loginToPlaycart()
+      })
+      Logger.info("Login successful")
+    })
+
+  program
+    .command("logout")
+    .description("Delete stored login credentials")
+    .option("--verbose", "set log level to debug")
+    .action(() => {
+      removeLoginCredentials()
+    })
+
+  program
+    .command("setup [projectPath]")
+    .description("Prints setup information and creates a configuration file")
+    .option("-m, --merchant <merchant>", "merchant to create config for")
+    .action(async (projectPath = ".", options) => {
+      await loadConfig({ options, allowIncomplete: true, projectPath: "." })
+      await withErrorHandler(() => printSetupHelp(projectPath, options))
+    })
+
+  program
+    .command("status [projectPath]")
+    .description("Print the configuration status")
+    .action(async (projectPath = ".", options) => {
+      await loadConfig({ options, allowIncomplete: true, projectPath: "." })
+      await withErrorHandler(() => printStatus(projectPath))
+    })
+
+  const searchTemplates = program
+    .command("st")
+    .alias("search-templates")
+    .description("Search templates management commands")
+
+  searchTemplates
+    .command("pull [projectPath]")
+    .description("Pull the search-templates source from the Nosto VSCode Web")
+    .option("-p, --paths <files...>", "specific file paths to fetch (space-separated list)")
+    .option("--dry-run", "perform a dry run without making changes")
+    .option("--verbose", "set log level to debug")
+    .option("-f --force", "skip checking state, pull all files")
+    .action(async (projectPath = ".", options) => {
+      await withSafeEnvironment({ projectPath, options, skipSanityCheck: true }, async () => {
+        await pullSearchTemplate({
+          paths: options.paths ?? [],
+          force: options.force ?? false
+        })
+      })
+    })
+
+  searchTemplates
+    .command("push [projectPath]")
+    .description("Push the search-templates source to the VSCode Web")
+    .option("-p, --paths <files...>", "specific file paths to deploy (space-separated list)")
+    .option("--dry-run", "perform a dry run without making changes")
+    .option("--verbose", "set log level to debug")
+    .option("-f --force", "skip checking state, push all files")
+    .action(async (projectPath = ".", options) => {
+      await withSafeEnvironment({ projectPath, options }, async () => {
+        await buildSearchTemplate({ watch: false })
+        await pushSearchTemplate({
+          paths: options.paths ?? [],
+          force: options.force ?? false
+        })
+      })
+    })
+
+  searchTemplates
+    .command("build [projectPath]")
+    .description("Build the search-templates locally")
+    .option("--dry-run", "perform a dry run without making changes")
+    .option("--verbose", "set log level to debug")
+    .option("-w, --watch", "watch for changes and rebuild")
+    .action(async (projectPath = ".", options) => {
+      await withSafeEnvironment({ projectPath, options }, async () => {
+        await buildSearchTemplate({ watch: options.watch ?? false })
+      })
+    })
+
+  searchTemplates
+    .command("dev [projectPath]")
+    .description("Build the search-templates locally, watch for changes and continuously upload")
+    .option("--dry-run", "perform a dry run without making changes")
+    .option("--verbose", "set log level to debug")
+    .action(async (projectPath = ".", options) => {
+      await withSafeEnvironment({ projectPath, options }, async () => {
+        await searchTemplateDevMode()
+      })
+    })
+
+  await program.parseAsync(argv)
+}

package/src/config/authConfig.ts

@@ -0,0 +1,42 @@
+import fs from "fs"
+import os from "os"
+import path from "path"
+import z from "zod"
+
+import { MissingConfigurationError } from "#errors/MissingConfigurationError.ts"
+
+import { type AuthConfig, AuthConfigSchema } from "./schema.ts"
+
+export const AuthConfigFilePath = path.join(os.homedir(), ".nosto", ".auth.json")
+
+export function authFileExists() {
+  return fs.existsSync(AuthConfigFilePath)
+}
+
+export function getAuthFileMissingError() {
+  return new MissingConfigurationError(
+    `Auth file not found at: ${AuthConfigFilePath}. You will not be able to use most commands without running 'nosto login' first.`
+  )
+}
+
+export function parseAuthFile({ allowIncomplete }: { allowIncomplete?: boolean }): AuthConfig {
+  if (!allowIncomplete && !authFileExists()) {
+    throw getAuthFileMissingError()
+  } else if (!authFileExists()) {
+    return { user: "", token: "", expiresAt: new Date(0) }
+  }
+
+  try {
+    const configContent = fs.readFileSync(AuthConfigFilePath, "utf-8")
+    const rawConfig = JSON.parse(configContent)
+    return AuthConfigSchema.parse(rawConfig)
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      throw new Error(`Invalid auth file at ${AuthConfigFilePath}: ${error.message}`)
+    }
+    if (error instanceof SyntaxError) {
+      throw new Error(`Invalid JSON in auth file at ${AuthConfigFilePath}: ${error.message}`)
+    }
+    throw error
+  }
+}

package/src/config/config.ts

@@ -0,0 +1,109 @@
+import { resolve } from "path"
+
+import { cleanUrl } from "#api/utils.ts"
+import { Logger } from "#console/logger.ts"
+import { MissingConfigurationError } from "#errors/MissingConfigurationError.ts"
+
+import { authFileExists, getAuthFileMissingError, parseAuthFile } from "./authConfig.ts"
+import { getEnvConfig } from "./envConfig.ts"
+import { parseConfigFile } from "./fileConfig.ts"
+import {
+  AuthConfigSchema,
+  type Config,
+  PersistentConfigSchema,
+  RuntimeConfigSchema,
+  SearchTemplatesConfigSchema
+} from "./schema.ts"
+import { parseSearchTemplatesConfigFile } from "./searchTemplatesConfig.ts"
+
+let isConfigLoaded = false
+let cachedConfig: Config = {
+  ...getDefaultConfig(),
+  auth: AuthConfigSchema.parse({
+    user: "",
+    token: "",
+    expiresAt: new Date(0)
+  }),
+  searchTemplates: {
+    mode: "unknown",
+    data: SearchTemplatesConfigSchema.parse({})
+  },
+  ...RuntimeConfigSchema.parse({})
+}
+
+export type LoadConfigProps = {
+  projectPath: string
+  options: object
+  allowIncomplete?: boolean
+}
+
+export async function loadConfig({ projectPath, options, allowIncomplete }: LoadConfigProps) {
+  const { dryRun, verbose } = RuntimeConfigSchema.parse({ ...options, projectPath })
+
+  if (isConfigLoaded) {
+    Logger.debug(`Using cached configuration`)
+    return cachedConfig
+  }
+
+  const fullPath = resolve(projectPath)
+  Logger.debug(`Loading configuration from folder: ${fullPath}`)
+  if (!allowIncomplete && !authFileExists()) {
+    throw getAuthFileMissingError()
+  }
+  const authConfig = parseAuthFile({ allowIncomplete })
+  const searchTemplatesConfig = await parseSearchTemplatesConfigFile({ projectPath })
+  const fileConfig = parseConfigFile({ projectPath, allowIncomplete })
+  const envConfig = getEnvConfig()
+
+  const baseConfig = allowIncomplete ? getDefaultConfig() : {}
+
+  const combinedConfig = {
+    ...baseConfig,
+    ...fileConfig,
+    ...envConfig
+  }
+  if (!combinedConfig.merchant && !allowIncomplete) {
+    throw new MissingConfigurationError("Invalid configuration: Missing merchant ID")
+  }
+
+  try {
+    const persistentConfig = PersistentConfigSchema.parse(combinedConfig)
+    cachedConfig = {
+      ...persistentConfig,
+      auth: authConfig,
+      searchTemplates: searchTemplatesConfig,
+      apiUrl: cleanUrl(persistentConfig.apiUrl),
+      libraryUrl: cleanUrl(persistentConfig.libraryUrl),
+      logLevel: verbose ? "debug" : persistentConfig.logLevel,
+      projectPath,
+      dryRun,
+      verbose
+    }
+    updateLoggerContext(cachedConfig)
+    isConfigLoaded = true
+    return cachedConfig
+  } catch (error) {
+    throw new Error("Failed to load configuration", { cause: error })
+  }
+}
+
+function updateLoggerContext(config: Config) {
+  Logger.context = {
+    logLevel: config.logLevel,
+    merchantId: config.merchant,
+    isDryRun: config.dryRun
+  }
+}
+
+export function getCachedConfig() {
+  return cachedConfig
+}
+export function getCachedSearchTemplatesConfig() {
+  return cachedConfig.searchTemplates.data
+}
+
+export function getDefaultConfig() {
+  return PersistentConfigSchema.parse({
+    merchant: ""
+  })
+}

package/src/config/envConfig.ts

@@ -0,0 +1,23 @@
+import { type EnvironmentConfig, EnvironmentConfigSchema } from "./schema.ts"
+
+export const EnvVariables = {
+  apiKey: "NOSTO_API_KEY",
+  merchant: "NOSTO_MERCHANT",
+  templatesEnv: "NOSTO_TEMPLATES_ENV",
+  apiUrl: "NOSTO_API_URL",
+  libraryUrl: "NOSTO_LIBRARY_URL",
+  logLevel: "NOSTO_LOG_LEVEL",
+  maxRequests: "NOSTO_MAX_REQUESTS"
+} satisfies Record<keyof EnvironmentConfig, string>
+
+export function getEnvConfig(): EnvironmentConfig {
+  const config = Object.entries(EnvVariables).reduce<Record<string, string>>((acc, [key, envVar]) => {
+    const value = process.env[envVar]
+    if (value) {
+      acc[key] = value
+    }
+    return acc
+  }, {})
+
+  return EnvironmentConfigSchema.parse(config)
+}

package/src/config/fileConfig.ts

@@ -0,0 +1,39 @@
+import fs from "fs"
+import path from "path"
+import z from "zod"
+
+import { Logger } from "#console/logger.ts"
+
+import { type PartialPersistentConfig, PartialPersistentConfigSchema } from "./schema.ts"
+
+export function parseConfigFile({
+  projectPath,
+  allowIncomplete
+}: {
+  projectPath: string
+  allowIncomplete?: boolean
+}): PartialPersistentConfig {
+  const configPath = path.join(projectPath, ".nosto.json")
+
+  const configFileMissing = !fs.existsSync(configPath)
+  if (allowIncomplete && configFileMissing) {
+    return {}
+  } else if (configFileMissing) {
+    Logger.warn(`Configuration file not found at: ${configPath}. Will try to use environment variables.`)
+    return {}
+  }
+
+  try {
+    const configContent = fs.readFileSync(configPath, "utf-8")
+    const rawConfig = JSON.parse(configContent)
+    return PartialPersistentConfigSchema.parse(rawConfig)
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      throw new Error(`Invalid configuration file at ${configPath}: ${error.message}`)
+    }
+    if (error instanceof SyntaxError) {
+      throw new Error(`Invalid JSON in configuration file at ${configPath}: ${error.message}`)
+    }
+    throw error
+  }
+}