@localess/cli 3.0.0 → 3.0.1-dev.20260325211243

package/README.md

@@ -249,6 +249,31 @@ const content = await client.getContentBySlug<Page>('home', { locale: 'en' });
 
 ---
 
+## AI Coding Agents
+
+This package ships a [`SKILL.md`](./SKILL.md) file that provides AI coding agents (GitHub Copilot, Claude Code, Cursor, and others) with accurate, up-to-date APIs, patterns, and best practices. Most agents automatically read `SKILL.md` when starting a session.
+
+### Using SKILL.md in your project
+
+`SKILL.md` is included in the npm package, so it is available locally after installation. Reference it from your project's `AGENTS.md` to ensure your agent reads accurate Localess documentation every session:
+
+```markdown
+## Localess
+
+@node_modules/@localess/cli/SKILL.md
+```
+
+The `@` prefix is the syntax used by most agent tools (GitHub Copilot, Claude Code, Cursor) to import file contents inline into the agent context.
+
+When you change the public API of this package, update `SKILL.md` alongside your code:
+
+- **New option or parameter** → add it to the relevant options table and usage example
+- **Changed behaviour** → update the description and any affected code snippets
+- **Deprecated API** → mark it clearly and point to the replacement
+- **New command or subcommand** → add a full entry with all flags and examples
+
+---
+
 ## License
 
 [MIT](../../LICENSE)

package/SKILL.md

@@ -0,0 +1,363 @@
+# SKILL: @localess/cli
+
+## Overview
+
+`@localess/cli` is the **command-line interface** for the Localess headless CMS platform. It enables:
+
+- Authenticating with a Localess instance
+- Pushing and pulling translations (flat JSON; nested format supported for pull only)
+- Generating TypeScript type definitions from the OpenAPI schema
+
+**Status:** Early development (v3.0.0). Requires Node.js >= 20.0.0.
+
+---
+
+## Installation
+
+```bash
+npm install -g @localess/cli
+# or use npx
+npx @localess/cli [command]
+```
+
+---
+
+## Authentication
+
+### Login
+
+Authenticate and persist credentials locally. Interactive prompts fill in any missing options.
+
+```bash
+localess login \
+  --origin https://my-localess.web.app \
+  --space YOUR_SPACE_ID \
+  --token YOUR_API_TOKEN
+```
+
+**Options:**
+
+| Flag                   | Description                     |
+|------------------------|---------------------------------|
+| `-o, --origin <url>`   | Localess instance URL           |
+| `-s, --space <id>`     | Space ID (from Space settings)  |
+| `-t, --token <token>`  | API token (masked input prompt) |
+
+**Behavior:**
+1. Checks for existing credentials (env vars or file)
+2. Prompts interactively for any missing options
+3. Validates credentials by calling the API
+4. Saves credentials to `.localess/credentials.json` (mode `0o600`)
+
+### Logout
+
+```bash
+localess logout
+```
+
+- Clears `.localess/credentials.json` (writes `{}`)
+- If authenticated via environment variables, instructs you to unset them manually
+
+---
+
+## Credential Storage
+
+Credentials are resolved in this priority order:
+
+1. **Environment variables** (highest priority)
+2. **`.localess/credentials.json`** (file-based)
+
+### Environment Variables
+
+```bash
+export LOCALESS_ORIGIN=https://my-localess.web.app
+export LOCALESS_SPACE=YOUR_SPACE_ID
+export LOCALESS_TOKEN=YOUR_API_TOKEN
+```
+
+Recommended for **CI/CD pipelines** — no `localess login` step needed.
+
+### File-based Credentials
+
+```json
+// .localess/credentials.json
+{
+  "origin": "https://my-localess.web.app",
+  "space": "YOUR_SPACE_ID",
+  "token": "YOUR_API_TOKEN"
+}
+```
+
+> **Add `.localess/credentials.json` to your `.gitignore`** to avoid committing secrets.
+
+---
+
+## Translations
+
+### Push Translations
+
+Upload a local JSON translation file to Localess.
+
+```bash
+localess translations push <locale> --path <file> [options]
+```
+
+**Arguments:**
+
+| Argument   | Description                         |
+|------------|-------------------------------------|
+| `<locale>` | ISO 639-1 locale code: `en`, `de`… |
+
+**Options:**
+
+| Flag                    | Default         | Description                                           |
+|-------------------------|-----------------|-------------------------------------------------------|
+| `-p, --path <path>`     | required        | Path to the translations JSON file                    |
+| `-f, --format <format>` | `flat`          | File format: `flat` only (**nested not yet implemented**) |
+| `-t, --type <type>`     | `add-missing`   | Update strategy: `add-missing` or `update-existing`   |
+| `--dry-run`             | `false`         | Preview changes without applying them                 |
+
+**Update Strategies:**
+
+| Strategy           | Behaviour                                                  |
+|--------------------|------------------------------------------------------------|
+| `add-missing`      | Only adds keys that don't yet exist in Localess            |
+| `update-existing`  | Only updates keys that already exist in Localess           |
+
+**File Formats:**
+
+*Flat (default — only supported format for push):*
+```json
+{
+  "common.submit": "Submit",
+  "nav.home": "Home",
+  "errors.required": "This field is required"
+}
+```
+
+> **⚠️ Nested format is not yet implemented for push.** Passing `--format nested` logs an error and exits without uploading. Use `flat` format only.
+
+**Examples:**
+
+```bash
+# Basic push — add missing translations only
+localess translations push en --path ./locales/en.json
+
+# Update existing translations (don't add new)
+localess translations push de --path ./locales/de.json --type update-existing
+
+# Preview changes without applying
+localess translations push fr --path ./locales/fr.json --dry-run
+```
+
+---
+
+### Pull Translations
+
+Download translations from Localess to a local JSON file.
+
+```bash
+localess translations pull <locale> --path <file> [options]
+```
+
+**Arguments:**
+
+| Argument   | Description                         |
+|------------|-------------------------------------|
+| `<locale>` | ISO 639-1 locale code: `en`, `de`… |
+
+**Options:**
+
+| Flag                    | Default   | Description                          |
+|-------------------------|-----------|--------------------------------------|
+| `-p, --path <path>`     | required  | Output file path                     |
+| `-f, --format <format>` | `flat`    | File format: `flat` or `nested`      |
+
+**Examples:**
+
+```bash
+# Pull as flat JSON
+localess translations pull en --path ./locales/en.json
+
+# Pull as nested JSON
+localess translations pull de --path ./locales/de.json --format nested
+```
+
+---
+
+## Type Generation
+
+Generate TypeScript type definitions from your Localess space's OpenAPI schema.
+
+```bash
+localess types generate [--path <output>]
+```
+
+**Options:**
+
+| Flag                | Default                       | Description                   |
+|---------------------|-------------------------------|-------------------------------|
+| `-p, --path <path>` | `.localess/localess.d.ts`     | Output file path              |
+
+> **Prerequisite:** The API token must have the **Development Tools** permission in Localess Space settings.
+
+**What it does:**
+1. Fetches the OpenAPI 3.0 spec from your space
+2. Extracts schema components
+3. Generates TypeScript `.d.ts` definitions with `openapi-typescript`
+
+**Examples:**
+
+```bash
+# Default output to .localess/localess.d.ts
+localess types generate
+
+# Custom output path
+localess types generate --path src/types/localess.d.ts
+```
+
+**Generated output:**
+
+```typescript
+// .localess/localess.d.ts (auto-generated — do not edit)
+export type Page = {
+  _id: string;
+  _schema: string;
+  title: string;
+  body: (HeroSection | CardGrid | RichTextBlock)[];
+};
+
+export type HeroSection = {
+  _id: string;
+  _schema: string;
+  headline: string;
+  subheadline?: string;
+  image?: ContentAsset;
+};
+
+// ... all schemas from your Localess space
+```
+
+**Using generated types:**
+
+```typescript
+import type { Page, HeroSection } from './.localess/localess';
+import { getLocalessClient } from "@localess/react";
+
+const client = getLocalessClient();
+const content = await client.getContentBySlug<Page>('home');
+// content.data is fully typed as Page
+```
+
+---
+
+## CI/CD Integration
+
+### GitHub Actions Example
+
+```yaml
+# .github/workflows/sync-translations.yml
+name: Sync translations
+
+on:
+  push:
+    paths:
+      - 'locales/**'
+
+jobs:
+  push-translations:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - run: npm install -g @localess/cli
+      - run: localess translations push en --path ./locales/en.json
+        env:
+          LOCALESS_ORIGIN: ${{ secrets.LOCALESS_ORIGIN }}
+          LOCALESS_SPACE: ${{ secrets.LOCALESS_SPACE_ID }}
+          LOCALESS_TOKEN: ${{ secrets.LOCALESS_TOKEN }}
+```
+
+### Pull Translations in CI
+
+```yaml
+      - run: localess translations pull en --path ./locales/en.json
+        env:
+          LOCALESS_ORIGIN: ${{ secrets.LOCALESS_ORIGIN }}
+          LOCALESS_SPACE: ${{ secrets.LOCALESS_SPACE_ID }}
+          LOCALESS_TOKEN: ${{ secrets.LOCALESS_TOKEN }}
+      - run: git diff --exit-code locales/ || (git commit -am "chore: sync translations" && git push)
+```
+
+### Generate Types in CI
+
+```yaml
+      - run: localess types generate --path src/types/localess.d.ts
+        env:
+          LOCALESS_ORIGIN: ${{ secrets.LOCALESS_ORIGIN }}
+          LOCALESS_SPACE: ${{ secrets.LOCALESS_SPACE_ID }}
+          LOCALESS_TOKEN: ${{ secrets.LOCALESS_TOKEN }}
+```
+
+---
+
+## Local Development Workflow
+
+```bash
+# 1. Authenticate once
+localess login
+
+# 2. Pull latest translations
+localess translations pull en --path ./locales/en.json
+
+# 3. Edit translations locally...
+
+# 4. Push back (dry-run first)
+localess translations push en --path ./locales/en.json --dry-run
+localess translations push en --path ./locales/en.json
+
+# 5. Generate types after schema changes in Localess
+localess types generate
+```
+
+---
+
+## .gitignore Recommendations
+
+```gitignore
+# Localess credentials (contains API token)
+.localess/credentials.json
+
+# Generated types are typically committed to the repo
+# but can be excluded if auto-generated in CI:
+# .localess/localess.d.ts
+```
+
+---
+
+## Files Written by the CLI
+
+| File                          | Created by                  | Permissions    | Purpose                        |
+|-------------------------------|-----------------------------|----------------|--------------------------------|
+| `.localess/credentials.json`  | `localess login`            | `0o600` (owner only) | Persisted auth credentials |
+| `.localess/localess.d.ts`     | `localess types generate`   | Standard       | Generated TypeScript types     |
+
+---
+
+## Best Practices
+
+1. **Use environment variables in CI/CD** — set `LOCALESS_ORIGIN`, `LOCALESS_SPACE`, `LOCALESS_TOKEN` as secrets. No `login` command needed.
+
+2. **Always dry-run before pushing translations** in automated scripts: add `--dry-run` first, inspect the output, then run without it.
+
+3. **Commit generated types** (`.localess/localess.d.ts`) to your repo so the whole team benefits from type safety without running the CLI.
+
+4. **Re-run `types generate` after any schema change** in the Localess CMS to keep types in sync.
+
+5. **Use `add-missing` strategy (default)** for initial import of translations; switch to `update-existing` when syncing copy changes.
+
+6. **Never commit `.localess/credentials.json`** — add it to `.gitignore` immediately after `localess login`.
+
+7. **Give the token minimum required permissions** — the `types generate` command needs "Development Tools" permission; other commands only need standard API access.

package/dist/index.js

@@ -123,6 +123,7 @@ function localessClient(options) {
   if (options.debug) {
     console.log(LOG_GROUP, "Client Options : ", options);
   }
+  const normalizedOrigin = options.origin.replace(/\/+$/, "");
   const fetchOptions = {
     redirect: "follow",
     headers: {
@@ -138,7 +139,7 @@ function localessClient(options) {
       if (options.debug) {
         console.log(LOG_GROUP, "getSpace()");
       }
-      let url = `${options.origin}/api/v1/spaces/${options.spaceId}?token=${options.token}`;
+      let url = `${normalizedOrigin}/api/v1/spaces/${options.spaceId}?token=${options.token}`;
       if (options.debug) {
         console.log(LOG_GROUP, "getSpace fetch url : ", url);
       }
@@ -177,7 +178,7 @@ function localessClient(options) {
       if (params?.excludeChildren) {
         excludeChildren = `&excludeChildren=${params.excludeChildren}`;
       }
-      let url = `${options.origin}/api/v1/spaces/${options.spaceId}/links?token=${options.token}${kind}${parentSlug}${excludeChildren}`;
+      let url = `${normalizedOrigin}/api/v1/spaces/${options.spaceId}/links?token=${options.token}${kind}${parentSlug}${excludeChildren}`;
       if (options.debug) {
         console.log(LOG_GROUP, "getLinks fetch url : ", url);
       }
@@ -215,7 +216,7 @@ function localessClient(options) {
       const locale = params?.locale ? `&locale=${params.locale}` : "";
       const resolveReference = params?.resolveReference ? `&resolveReference=${params.resolveReference}` : "";
       const resolveLink = params?.resolveLink ? `&resolveLink=${params.resolveLink}` : "";
-      let url = `${options.origin}/api/v1/spaces/${options.spaceId}/contents/slugs/${slug}?token=${options.token}${version}${locale}${resolveReference}${resolveLink}`;
+      let url = `${normalizedOrigin}/api/v1/spaces/${options.spaceId}/contents/slugs/${slug}?token=${options.token}${version}${locale}${resolveReference}${resolveLink}`;
       if (options.debug) {
         console.log(LOG_GROUP, "getContentBySlug fetch url : ", url);
       }
@@ -253,7 +254,7 @@ function localessClient(options) {
       const locale = params?.locale ? `&locale=${params.locale}` : "";
       const resolveReference = params?.resolveReference ? `&resolveReference=${params.resolveReference}` : "";
       const resolveLink = params?.resolveLink ? `&resolveLink=${params.resolveLink}` : "";
-      let url = `${options.origin}/api/v1/spaces/${options.spaceId}/contents/${id}?token=${options.token}${version}${locale}${resolveReference}${resolveLink}`;
+      let url = `${normalizedOrigin}/api/v1/spaces/${options.spaceId}/contents/${id}?token=${options.token}${version}${locale}${resolveReference}${resolveLink}`;
       if (options.debug) {
         console.log(LOG_GROUP, "getContentById fetch url : ", url);
       }
@@ -288,7 +289,7 @@ function localessClient(options) {
       if (params?.version && params.version == "draft") {
         version = `&version=${params.version}`;
       }
-      let url = `${options.origin}/api/v1/spaces/${options.spaceId}/translations/${locale}?token=${options.token}${version}`;
+      let url = `${normalizedOrigin}/api/v1/spaces/${options.spaceId}/translations/${locale}?token=${options.token}${version}`;
       if (options.debug) {
         console.log(LOG_GROUP, "getTranslations fetch url : ", url);
       }
@@ -317,7 +318,7 @@ function localessClient(options) {
         console.log(LOG_GROUP, "updateTranslations() type : ", type);
         console.log(LOG_GROUP, "updateTranslations() values : ", JSON.stringify(values));
       }
-      let url = `${options.origin}/api/v1/spaces/${options.spaceId}/translations/${locale}`;
+      let url = `${normalizedOrigin}/api/v1/spaces/${options.spaceId}/translations/${locale}`;
       if (options.debug) {
         console.log(LOG_GROUP, "updateTranslations fetch url : ", url);
       }
@@ -347,7 +348,7 @@ function localessClient(options) {
       if (options.debug) {
         console.log(LOG_GROUP, "getOpenApi()");
       }
-      let url = `${options.origin}/api/v1/spaces/${options.spaceId}/open-api?token=${options.token}`;
+      let url = `${normalizedOrigin}/api/v1/spaces/${options.spaceId}/open-api?token=${options.token}`;
       if (options.debug) {
         console.log(LOG_GROUP, "getOpenApi fetch url : ", url);
       }
@@ -371,13 +372,13 @@ function localessClient(options) {
       }
     },
     syncScriptUrl() {
-      return `${options.origin}/scripts/sync-v1.js`;
+      return `${normalizedOrigin}/scripts/sync-v1.js`;
     },
     assetLink(asset) {
       if (typeof asset === "string") {
-        return `${options.origin}/api/v1/spaces/${options.spaceId}/assets/${asset}`;
+        return `${normalizedOrigin}/api/v1/spaces/${options.spaceId}/assets/${asset}`;
       } else {
-        return `${options.origin}/api/v1/spaces/${options.spaceId}/assets/${asset.uri}`;
+        return `${normalizedOrigin}/api/v1/spaces/${options.spaceId}/assets/${asset.uri}`;
       }
     }
   };

package/dist/index.mjs

@@ -100,6 +100,7 @@ function localessClient(options) {
   if (options.debug) {
     console.log(LOG_GROUP, "Client Options : ", options);
   }
+  const normalizedOrigin = options.origin.replace(/\/+$/, "");
   const fetchOptions = {
     redirect: "follow",
     headers: {
@@ -115,7 +116,7 @@ function localessClient(options) {
       if (options.debug) {
         console.log(LOG_GROUP, "getSpace()");
       }
-      let url = `${options.origin}/api/v1/spaces/${options.spaceId}?token=${options.token}`;
+      let url = `${normalizedOrigin}/api/v1/spaces/${options.spaceId}?token=${options.token}`;
       if (options.debug) {
         console.log(LOG_GROUP, "getSpace fetch url : ", url);
       }
@@ -154,7 +155,7 @@ function localessClient(options) {
       if (params?.excludeChildren) {
         excludeChildren = `&excludeChildren=${params.excludeChildren}`;
       }
-      let url = `${options.origin}/api/v1/spaces/${options.spaceId}/links?token=${options.token}${kind}${parentSlug}${excludeChildren}`;
+      let url = `${normalizedOrigin}/api/v1/spaces/${options.spaceId}/links?token=${options.token}${kind}${parentSlug}${excludeChildren}`;
       if (options.debug) {
         console.log(LOG_GROUP, "getLinks fetch url : ", url);
       }
@@ -192,7 +193,7 @@ function localessClient(options) {
       const locale = params?.locale ? `&locale=${params.locale}` : "";
       const resolveReference = params?.resolveReference ? `&resolveReference=${params.resolveReference}` : "";
       const resolveLink = params?.resolveLink ? `&resolveLink=${params.resolveLink}` : "";
-      let url = `${options.origin}/api/v1/spaces/${options.spaceId}/contents/slugs/${slug}?token=${options.token}${version}${locale}${resolveReference}${resolveLink}`;
+      let url = `${normalizedOrigin}/api/v1/spaces/${options.spaceId}/contents/slugs/${slug}?token=${options.token}${version}${locale}${resolveReference}${resolveLink}`;
       if (options.debug) {
         console.log(LOG_GROUP, "getContentBySlug fetch url : ", url);
       }
@@ -230,7 +231,7 @@ function localessClient(options) {
       const locale = params?.locale ? `&locale=${params.locale}` : "";
       const resolveReference = params?.resolveReference ? `&resolveReference=${params.resolveReference}` : "";
       const resolveLink = params?.resolveLink ? `&resolveLink=${params.resolveLink}` : "";
-      let url = `${options.origin}/api/v1/spaces/${options.spaceId}/contents/${id}?token=${options.token}${version}${locale}${resolveReference}${resolveLink}`;
+      let url = `${normalizedOrigin}/api/v1/spaces/${options.spaceId}/contents/${id}?token=${options.token}${version}${locale}${resolveReference}${resolveLink}`;
       if (options.debug) {
         console.log(LOG_GROUP, "getContentById fetch url : ", url);
       }
@@ -265,7 +266,7 @@ function localessClient(options) {
       if (params?.version && params.version == "draft") {
         version = `&version=${params.version}`;
       }
-      let url = `${options.origin}/api/v1/spaces/${options.spaceId}/translations/${locale}?token=${options.token}${version}`;
+      let url = `${normalizedOrigin}/api/v1/spaces/${options.spaceId}/translations/${locale}?token=${options.token}${version}`;
       if (options.debug) {
         console.log(LOG_GROUP, "getTranslations fetch url : ", url);
       }
@@ -294,7 +295,7 @@ function localessClient(options) {
         console.log(LOG_GROUP, "updateTranslations() type : ", type);
         console.log(LOG_GROUP, "updateTranslations() values : ", JSON.stringify(values));
       }
-      let url = `${options.origin}/api/v1/spaces/${options.spaceId}/translations/${locale}`;
+      let url = `${normalizedOrigin}/api/v1/spaces/${options.spaceId}/translations/${locale}`;
       if (options.debug) {
         console.log(LOG_GROUP, "updateTranslations fetch url : ", url);
       }
@@ -324,7 +325,7 @@ function localessClient(options) {
       if (options.debug) {
         console.log(LOG_GROUP, "getOpenApi()");
       }
-      let url = `${options.origin}/api/v1/spaces/${options.spaceId}/open-api?token=${options.token}`;
+      let url = `${normalizedOrigin}/api/v1/spaces/${options.spaceId}/open-api?token=${options.token}`;
       if (options.debug) {
         console.log(LOG_GROUP, "getOpenApi fetch url : ", url);
       }
@@ -348,13 +349,13 @@ function localessClient(options) {
       }
     },
     syncScriptUrl() {
-      return `${options.origin}/scripts/sync-v1.js`;
+      return `${normalizedOrigin}/scripts/sync-v1.js`;
     },
     assetLink(asset) {
       if (typeof asset === "string") {
-        return `${options.origin}/api/v1/spaces/${options.spaceId}/assets/${asset}`;
+        return `${normalizedOrigin}/api/v1/spaces/${options.spaceId}/assets/${asset}`;
       } else {
-        return `${options.origin}/api/v1/spaces/${options.spaceId}/assets/${asset.uri}`;
+        return `${normalizedOrigin}/api/v1/spaces/${options.spaceId}/assets/${asset.uri}`;
       }
     }
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@localess/cli",
-  "version": "3.0.0",
+  "version": "3.0.1-dev.20260325211243",
   "description": "Localess Command Line.",
   "keywords": [
     "localess",
@@ -13,7 +13,8 @@
   "homepage": "https://github.com/Lessify/localess-js",
   "sideEffects": false,
   "files": [
-    "dist"
+    "dist",
+    "SKILL.md"
   ],
   "exports": {
     ".": {