@nuxtjp/localized-site 0.0.0-stage → 0.1.1

package/package.json

@@ -1,6 +1,78 @@
 {
   "name": "@nuxtjp/localized-site",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Contract-first Japanese and English public-site module for Nuxt",
+  "type": "module",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": "^22.19.0 || ^24.11.0",
+    "pnpm": ">=10 <11"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "examples",
+    "schemas",
+    "validator",
+    "LICENSE",
+    "README.md",
+    "NOTICE",
+    "LICENSE-ASSETS",
+    "LICENSE-PREVIOUS",
+    "README.ja.md"
+  ],
+  "bin": {
+    "nuxtjp-localized-site": "./bin/nuxtjp-localized-site.mjs"
+  },
+  "main": "./dist/module.mjs",
+  "types": "./dist/types.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/types.d.mts",
+      "import": "./dist/module.mjs"
+    },
+    "./core": {
+      "types": "./dist/runtime/core/index.d.ts",
+      "import": "./dist/runtime/core/index.js"
+    },
+    "./validator": {
+      "types": "./validator/content/index.d.ts",
+      "import": "./validator/content/index.js"
+    },
+    "./schema": "./schemas/localized-site-v1.schema.json"
+  },
+  "peerDependencies": {
+    "nuxt": "^4.5.1",
+    "vue": "^3.5.40"
+  },
+  "dependencies": {
+    "@nuxt/kit": "4.5.1",
+    "@nuxt/schema": "4.5.1"
+  },
+  "devDependencies": {
+    "@nuxt/module-builder": "1.0.2",
+    "@types/node": "24.12.0",
+    "nuxt": "4.5.1",
+    "typescript": "5.9.3",
+    "vitest": "4.1.11",
+    "vue": "3.5.43",
+    "vue-tsc": "3.2.8"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nuxtjp/nuxt-localized-site.git"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build:module": "nuxt-module-build build",
+    "build:validator": "tsc -p tsconfig.validator.json",
+    "build": "pnpm run build:validator && pnpm run build:module && nuxt build playground",
+    "typecheck": "vue-tsc --noEmit --project tsconfig.json",
+    "test": "vitest run",
+    "validate:example": "node ./bin/nuxtjp-localized-site.mjs validate --content-root ./examples/content"
+  }
 }

package/schemas/localized-site-v1.schema.json

@@ -0,0 +1,139 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "nuxtjp://localized-site/site-config/v1",
+  "title": "NuxtJP localized public site",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema",
+    "siteId",
+    "serviceId",
+    "origin",
+    "audienceScope",
+    "defaultLocale",
+    "locales",
+    "externalActions",
+    "content"
+  ],
+  "properties": {
+    "schema": { "const": "nuxtjp://localized-site/site-config/v1" },
+    "siteId": { "$ref": "#/$defs/id" },
+    "serviceId": { "$ref": "#/$defs/id" },
+    "origin": { "type": "string", "format": "uri", "maxLength": 500 },
+    "audienceScope": { "enum": ["japan", "global"] },
+    "defaultLocale": { "$ref": "#/$defs/locale" },
+    "fallbackLocale": { "$ref": "#/$defs/locale" },
+    "prefixDefaultLocale": { "type": "boolean" },
+    "locales": {
+      "type": "array",
+      "prefixItems": [{ "const": "ja" }, { "const": "en" }],
+      "minItems": 2,
+      "maxItems": 2
+    },
+    "externalActions": { "const": false },
+    "content": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["ja", "en"],
+      "properties": {
+        "ja": { "$ref": "#/$defs/localeContent" },
+        "en": { "$ref": "#/$defs/localeContent" }
+      }
+    }
+  },
+  "$defs": {
+    "locale": { "enum": ["ja", "en"] },
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+      "minLength": 1,
+      "maxLength": 80
+    },
+    "text": { "type": "string", "minLength": 1, "maxLength": 4000 },
+    "notice": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["label", "summary"],
+      "properties": {
+        "label": { "$ref": "#/$defs/text" },
+        "summary": { "$ref": "#/$defs/text" }
+      }
+    },
+    "feature": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "title", "summary"],
+      "properties": {
+        "id": { "$ref": "#/$defs/id" },
+        "title": { "$ref": "#/$defs/text" },
+        "summary": { "$ref": "#/$defs/text" }
+      }
+    },
+    "section": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "title", "body"],
+      "properties": {
+        "id": { "$ref": "#/$defs/id" },
+        "title": { "$ref": "#/$defs/text" },
+        "body": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/text" },
+          "minItems": 1
+        }
+      }
+    },
+    "document": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["slug", "title", "summary", "sections"],
+      "properties": {
+        "slug": { "type": "string", "pattern": "^/docs(?:/.*)?$" },
+        "title": { "$ref": "#/$defs/text" },
+        "summary": { "$ref": "#/$defs/text" },
+        "sections": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/section" },
+          "minItems": 1
+        }
+      }
+    },
+    "docs": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["overview", "gettingStarted", "security"],
+      "properties": {
+        "overview": { "$ref": "#/$defs/document" },
+        "gettingStarted": { "$ref": "#/$defs/document" },
+        "security": { "$ref": "#/$defs/document" }
+      }
+    },
+    "localeContent": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "brand",
+        "tagline",
+        "summary",
+        "features",
+        "docs",
+        "privacy",
+        "contact"
+      ],
+      "properties": {
+        "brand": { "$ref": "#/$defs/text" },
+        "tagline": { "$ref": "#/$defs/text" },
+        "summary": { "$ref": "#/$defs/text" },
+        "features": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/feature" },
+          "minItems": 3,
+          "maxItems": 3
+        },
+        "docs": { "$ref": "#/$defs/docs" },
+        "privacy": { "$ref": "#/$defs/notice" },
+        "contact": { "$ref": "#/$defs/notice" }
+      }
+    }
+  }
+}

package/schemas/public-maintenance-state-v1.schema.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "nuxtjp://public/maintenance-state/v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "generatedAt", "expiresAt", "global", "services"],
+  "properties": {
+    "schema": { "const": "nuxtjp://public/maintenance-state/v1" },
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "expiresAt": { "type": "string", "format": "date-time" },
+    "global": { "$ref": "#/$defs/status" },
+    "services": {
+      "type": "array",
+      "maxItems": 128,
+      "items": { "$ref": "#/$defs/target" }
+    }
+  },
+  "$defs": {
+    "message": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["ja", "en"],
+      "properties": {
+        "ja": { "type": "string", "minLength": 1, "maxLength": 240 },
+        "en": { "type": "string", "minLength": 1, "maxLength": 240 }
+      }
+    },
+    "status": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["state", "message", "expiresAt"],
+      "properties": {
+        "state": { "enum": ["operational", "maintenance"] },
+        "message": { "$ref": "#/$defs/message" },
+        "expiresAt": { "type": "string", "format": "date-time" }
+      }
+    },
+    "target": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["serviceId", "state", "message", "expiresAt"],
+      "properties": {
+        "serviceId": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$" },
+        "state": { "enum": ["operational", "maintenance"] },
+        "message": { "$ref": "#/$defs/message" },
+        "expiresAt": { "type": "string", "format": "date-time" }
+      }
+    }
+  }
+}

package/validator/content/cli.d.ts

@@ -0,0 +1,5 @@
+export interface CliOutput {
+    out(value: string): void;
+    error(value: string): void;
+}
+export declare function runValidatorCli(args: string[], output: CliOutput): Promise<number>;

package/validator/content/cli.js

@@ -0,0 +1,31 @@
+import { resolve } from 'node:path';
+import { loadSiteConfig } from './load.js';
+function contentRoot(args) {
+    if (args[0] !== 'validate')
+        throw new Error('expected the validate command');
+    const flagIndex = args.indexOf('--content-root');
+    const value = flagIndex >= 0 ? args[flagIndex + 1] : undefined;
+    if (!value || args.length !== 3) {
+        throw new Error('usage: nuxtjp-localized-site validate --content-root <path>');
+    }
+    return resolve(value);
+}
+export async function runValidatorCli(args, output) {
+    try {
+        const config = loadSiteConfig(contentRoot(args));
+        output.out(JSON.stringify({
+            schema: 'nuxtjp://localized-site/validation-result/v1',
+            valid: true,
+            siteId: config.siteId,
+            serviceId: config.serviceId,
+            locales: config.locales,
+            routes: ['/', '/docs', '/docs/getting-started', '/docs/security'],
+            externalActions: config.externalActions
+        }, null, 2));
+        return 0;
+    }
+    catch (error) {
+        output.error(error instanceof Error ? error.message : 'site validation failed');
+        return 1;
+    }
+}

package/validator/content/errors.d.ts

@@ -0,0 +1,4 @@
+export declare class SiteContractError extends Error {
+    readonly issues: string[];
+    constructor(issues: string[]);
+}

package/validator/content/errors.js

@@ -0,0 +1,8 @@
+export class SiteContractError extends Error {
+    issues;
+    constructor(issues) {
+        super(`site contract is invalid:\n- ${issues.join('\n- ')}`);
+        this.name = 'SiteContractError';
+        this.issues = issues;
+    }
+}

package/validator/content/index.d.ts

@@ -0,0 +1,4 @@
+export { SiteContractError } from './errors.js';
+export { loadSiteConfig } from './load.js';
+export { validateSiteConfig, defineSiteConfig } from './validation/site-config.js';
+export type { ResolvedSiteConfig, SiteConfig, SupportedLocale } from '../contracts/types.js';

package/validator/content/index.js

@@ -0,0 +1,3 @@
+export { SiteContractError } from './errors.js';
+export { loadSiteConfig } from './load.js';
+export { validateSiteConfig, defineSiteConfig } from './validation/site-config.js';

package/validator/content/load.d.ts

@@ -0,0 +1,2 @@
+import type { ResolvedSiteConfig } from '../contracts/types.js';
+export declare function loadSiteConfig(contentRoot: string): ResolvedSiteConfig;

package/validator/content/load.js

@@ -0,0 +1,25 @@
+import { readFileSync, realpathSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { SiteContractError } from './errors.js';
+import { validateSiteConfig } from './validation/site-config.js';
+export function loadSiteConfig(contentRoot) {
+    let root;
+    try {
+        root = realpathSync(contentRoot);
+        if (!statSync(root).isDirectory())
+            throw new Error('not a directory');
+    }
+    catch {
+        throw new SiteContractError([`content root is not a readable directory: ${contentRoot}`]);
+    }
+    const file = join(root, 'site.config.json');
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : 'unknown read error';
+        throw new SiteContractError([`cannot read ${file}: ${detail}`]);
+    }
+    return validateSiteConfig(parsed);
+}

package/validator/content/validation/completeness.d.ts

@@ -0,0 +1,2 @@
+import type { LocaleContent } from '../../contracts/types.js';
+export declare function validateCompleteness(ja: LocaleContent, en: LocaleContent, issues: string[]): void;

package/validator/content/validation/completeness.js

@@ -0,0 +1,21 @@
+import { DOCUMENT_IDS } from '../../contracts/types.js';
+function sameIds(left, right, path, issues) {
+    const leftIds = left.map(item => item.id);
+    const rightIds = right.map(item => item.id);
+    if (JSON.stringify(leftIds) !== JSON.stringify(rightIds)) {
+        issues.push(`${path} must use the same ids and order in ja and en`);
+    }
+}
+function compareDocument(id, ja, en, issues) {
+    const jaDocument = ja.docs[id];
+    const enDocument = en.docs[id];
+    if (jaDocument.slug !== enDocument.slug) {
+        issues.push(`content.${id}.slug must match in ja and en`);
+    }
+    sameIds(jaDocument.sections, enDocument.sections, `content.${id}.sections`, issues);
+}
+export function validateCompleteness(ja, en, issues) {
+    sameIds(ja.features, en.features, 'content.features', issues);
+    for (const id of DOCUMENT_IDS)
+        compareDocument(id, ja, en, issues);
+}

package/validator/content/validation/locale-content.d.ts

@@ -0,0 +1,2 @@
+import type { LocaleContent } from '../../contracts/types.js';
+export declare function localeContent(value: unknown, path: string, issues: string[]): LocaleContent;

package/validator/content/validation/locale-content.js

@@ -0,0 +1,86 @@
+import { DOCUMENT_IDS } from '../../contracts/types.js';
+import { identifier, onlyKeys, record, text, textList } from './primitives.js';
+const documentSlugs = {
+    overview: '/docs',
+    gettingStarted: '/docs/getting-started',
+    security: '/docs/security'
+};
+function feature(value, path, issues) {
+    const item = record(value, path, issues);
+    onlyKeys(item, ['id', 'title', 'summary'], path, issues);
+    return {
+        id: identifier(item.id, `${path}.id`, issues),
+        title: text(item.title, `${path}.title`, issues, 160),
+        summary: text(item.summary, `${path}.summary`, issues, 500)
+    };
+}
+function features(value, path, issues) {
+    if (!Array.isArray(value) || value.length !== 3) {
+        issues.push(`${path} must contain exactly three features`);
+    }
+    const result = Array.isArray(value)
+        ? value.map((item, index) => feature(item, `${path}[${index}]`, issues))
+        : [];
+    if (new Set(result.map(item => item.id)).size !== result.length) {
+        issues.push(`${path} feature ids must be unique`);
+    }
+    return result;
+}
+function section(value, path, issues) {
+    const item = record(value, path, issues);
+    onlyKeys(item, ['id', 'title', 'body'], path, issues);
+    return {
+        id: identifier(item.id, `${path}.id`, issues),
+        title: text(item.title, `${path}.title`, issues, 160),
+        body: textList(item.body, `${path}.body`, issues)
+    };
+}
+function document(value, id, path, issues) {
+    const item = record(value, path, issues);
+    onlyKeys(item, ['slug', 'title', 'summary', 'sections'], path, issues);
+    const slug = text(item.slug, `${path}.slug`, issues, 80);
+    if (slug !== documentSlugs[id]) {
+        issues.push(`${path}.slug must be ${documentSlugs[id]}`);
+    }
+    const sections = Array.isArray(item.sections)
+        ? item.sections.map((entry, index) => section(entry, `${path}.sections[${index}]`, issues))
+        : [];
+    if (sections.length === 0)
+        issues.push(`${path}.sections must be a non-empty array`);
+    if (new Set(sections.map(item => item.id)).size !== sections.length) {
+        issues.push(`${path}.section ids must be unique`);
+    }
+    return {
+        slug,
+        title: text(item.title, `${path}.title`, issues, 160),
+        summary: text(item.summary, `${path}.summary`, issues, 500),
+        sections
+    };
+}
+function notice(value, path, issues) {
+    const item = record(value, path, issues);
+    onlyKeys(item, ['label', 'summary'], path, issues);
+    return {
+        label: text(item.label, `${path}.label`, issues, 160),
+        summary: text(item.summary, `${path}.summary`, issues, 1000)
+    };
+}
+export function localeContent(value, path, issues) {
+    const item = record(value, path, issues);
+    onlyKeys(item, ['brand', 'tagline', 'summary', 'features', 'docs', 'privacy', 'contact'], path, issues);
+    const docs = record(item.docs, `${path}.docs`, issues);
+    onlyKeys(docs, DOCUMENT_IDS, `${path}.docs`, issues);
+    return {
+        brand: text(item.brand, `${path}.brand`, issues, 160),
+        tagline: text(item.tagline, `${path}.tagline`, issues, 240),
+        summary: text(item.summary, `${path}.summary`, issues, 1000),
+        features: features(item.features, `${path}.features`, issues),
+        docs: {
+            overview: document(docs.overview, 'overview', `${path}.docs.overview`, issues),
+            gettingStarted: document(docs.gettingStarted, 'gettingStarted', `${path}.docs.gettingStarted`, issues),
+            security: document(docs.security, 'security', `${path}.docs.security`, issues)
+        },
+        privacy: notice(item.privacy, `${path}.privacy`, issues),
+        contact: notice(item.contact, `${path}.contact`, issues)
+    };
+}

package/validator/content/validation/primitives.d.ts

@@ -0,0 +1,9 @@
+import type { SupportedLocale } from '../../contracts/types.js';
+export type UnknownRecord = Record<string, unknown>;
+export declare function record(value: unknown, path: string, issues: string[]): UnknownRecord;
+export declare function onlyKeys(value: UnknownRecord, allowed: readonly string[], path: string, issues: string[]): void;
+export declare function text(value: unknown, path: string, issues: string[], maximum?: number): string;
+export declare function identifier(value: unknown, path: string, issues: string[]): string;
+export declare function locale(value: unknown, path: string, issues: string[]): SupportedLocale;
+export declare function textList(value: unknown, path: string, issues: string[]): string[];
+export declare function exactBoolean(value: unknown, expected: boolean, path: string, issues: string[]): boolean;

package/validator/content/validation/primitives.js

@@ -0,0 +1,48 @@
+export function record(value, path, issues) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        issues.push(`${path} must be an object`);
+        return {};
+    }
+    return value;
+}
+export function onlyKeys(value, allowed, path, issues) {
+    for (const key of Object.keys(value)) {
+        if (!allowed.includes(key))
+            issues.push(`${path}.${key} is not allowed`);
+    }
+}
+export function text(value, path, issues, maximum = 4000) {
+    if (typeof value !== 'string' || value.trim() === '') {
+        issues.push(`${path} must be a non-empty string`);
+        return '';
+    }
+    if (value.length > maximum)
+        issues.push(`${path} exceeds ${maximum} characters`);
+    return value;
+}
+export function identifier(value, path, issues) {
+    const result = text(value, path, issues, 80);
+    if (result && !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(result)) {
+        issues.push(`${path} must be a kebab-case identifier`);
+    }
+    return result;
+}
+export function locale(value, path, issues) {
+    if (value !== 'ja' && value !== 'en') {
+        issues.push(`${path} must be ja or en`);
+        return 'ja';
+    }
+    return value;
+}
+export function textList(value, path, issues) {
+    if (!Array.isArray(value) || value.length === 0) {
+        issues.push(`${path} must be a non-empty array`);
+        return [];
+    }
+    return value.map((entry, index) => text(entry, `${path}[${index}]`, issues));
+}
+export function exactBoolean(value, expected, path, issues) {
+    if (value !== expected)
+        issues.push(`${path} must be ${String(expected)}`);
+    return expected;
+}

package/validator/content/validation/site-config.d.ts

@@ -0,0 +1,3 @@
+import type { ResolvedSiteConfig, SiteConfig } from '../../contracts/types.js';
+export declare function validateSiteConfig(value: unknown): ResolvedSiteConfig;
+export declare function defineSiteConfig<const Config extends SiteConfig>(config: Config): Config;

package/validator/content/validation/site-config.js

@@ -0,0 +1,88 @@
+import { SITE_CONFIG_SCHEMA } from '../../contracts/types.js';
+import { SiteContractError } from '../errors.js';
+import { validateCompleteness } from './completeness.js';
+import { localeContent } from './locale-content.js';
+import { exactBoolean, identifier, locale, onlyKeys, record, text } from './primitives.js';
+const rootKeys = [
+    'schema',
+    'siteId',
+    'serviceId',
+    'origin',
+    'audienceScope',
+    'defaultLocale',
+    'fallbackLocale',
+    'prefixDefaultLocale',
+    'locales',
+    'externalActions',
+    'content'
+];
+function origin(value, issues) {
+    const input = text(value, 'origin', issues, 500);
+    try {
+        const parsed = new URL(input);
+        if (!['http:', 'https:'].includes(parsed.protocol))
+            throw new Error('protocol');
+        if (parsed.username || parsed.password || parsed.search || parsed.hash)
+            throw new Error('parts');
+        parsed.pathname = parsed.pathname === '/' ? '' : parsed.pathname.replace(/\/+$/, '');
+        return parsed.toString().replace(/\/$/, '');
+    }
+    catch {
+        issues.push('origin must be an HTTP(S) URL without credentials, query, or fragment');
+        return 'http://localhost';
+    }
+}
+function audience(value, issues) {
+    if (value !== 'japan' && value !== 'global') {
+        issues.push('audienceScope must be japan or global');
+        return 'japan';
+    }
+    return value;
+}
+function locales(value, issues) {
+    if (!Array.isArray(value) || value.length !== 2 || value[0] !== 'ja' || value[1] !== 'en') {
+        issues.push('locales must be exactly ["ja", "en"]');
+    }
+    return ['ja', 'en'];
+}
+export function validateSiteConfig(value) {
+    const issues = [];
+    const root = record(value, 'site.config.json', issues);
+    onlyKeys(root, rootKeys, 'site.config.json', issues);
+    if (root.schema !== SITE_CONFIG_SCHEMA) {
+        issues.push(`schema must be ${SITE_CONFIG_SCHEMA}`);
+    }
+    const defaultLocale = locale(root.defaultLocale, 'defaultLocale', issues);
+    const fallbackLocale = root.fallbackLocale === undefined
+        ? (defaultLocale === 'ja' ? 'en' : 'ja')
+        : locale(root.fallbackLocale, 'fallbackLocale', issues);
+    const prefixDefaultLocale = root.prefixDefaultLocale === undefined
+        ? false
+        : exactBoolean(root.prefixDefaultLocale, root.prefixDefaultLocale === true, 'prefixDefaultLocale', issues);
+    const content = record(root.content, 'content', issues);
+    onlyKeys(content, ['ja', 'en'], 'content', issues);
+    const ja = localeContent(content.ja, 'content.ja', issues);
+    const en = localeContent(content.en, 'content.en', issues);
+    validateCompleteness(ja, en, issues);
+    exactBoolean(root.externalActions, false, 'externalActions', issues);
+    const result = {
+        schema: SITE_CONFIG_SCHEMA,
+        siteId: identifier(root.siteId, 'siteId', issues),
+        serviceId: identifier(root.serviceId, 'serviceId', issues),
+        origin: origin(root.origin, issues),
+        audienceScope: audience(root.audienceScope, issues),
+        defaultLocale,
+        fallbackLocale,
+        prefixDefaultLocale,
+        locales: locales(root.locales, issues),
+        externalActions: false,
+        content: { ja, en }
+    };
+    if (issues.length > 0)
+        throw new SiteContractError(issues);
+    return result;
+}
+export function defineSiteConfig(config) {
+    validateSiteConfig(config);
+    return config;
+}