@nyaitter/nap 0.0.0-stage → 0.2.0

package/client/nap-page.js

@@ -0,0 +1,187 @@
+// NAP-Page: ページを NAP の版で管理するためのライブラリ。
+//
+// 使い方:
+//   import { createNapPage } from './nap-page.js';
+//   const page = createNapPage({
+//       source: '<所有者>/<リポジトリ>',
+//       rawBase: 'https://cdn.nyaitter.jp',   // 任意。既定はこの CDN
+//       currentVersionId: '<今の版ID>',        // 任意
+//   });
+//   const { hasUpdate, latest } = await page.checkUpdate();
+//   if (hasUpdate) {
+//       const result = await page.fetchVersion(latest.id);
+//       await page.store(result);       // Cache Storage へ検証済みのファイルを入れる
+//       await page.activate(latest.id); // 旧い版のキャッシュを消す
+//   }
+//
+// 取得と照合は nap-client が担う。このライブラリは、版の発見・更新確認と、
+// ブラウザの Cache Storage への格納を担当する。
+
+import { createClient } from './nap-client.js';
+
+const MIME_TYPES = {
+    '.html': 'text/html; charset=utf-8',
+    '.js': 'text/javascript; charset=utf-8',
+    '.mjs': 'text/javascript; charset=utf-8',
+    '.css': 'text/css; charset=utf-8',
+    '.json': 'application/json; charset=utf-8',
+    '.txt': 'text/plain; charset=utf-8',
+    '.svg': 'image/svg+xml',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.ico': 'image/x-icon',
+    '.wasm': 'application/wasm',
+    '.gz': 'application/gzip',
+};
+
+function typeFor(filePath) {
+    const dot = filePath.lastIndexOf('.');
+    const ext = dot >= 0 ? filePath.slice(dot).toLowerCase() : '';
+    return MIME_TYPES[ext] || 'application/octet-stream';
+}
+
+// 取得結果を、Cache Storage に置くパスの組へ平らにする。本体と構成員が対象。
+function flattenInto(out, prefix, result) {
+    for (const [rel, bytes] of Object.entries(result.files || {})) {
+        out[prefix + rel] = bytes;
+    }
+    for (const [ref, lib] of Object.entries(result.libraries || {})) {
+        flattenInto(out, `${prefix}nap_modules/${ref}/`, lib);
+    }
+}
+
+export function createNapPage(options = {}) {
+    const { source, rawBase = 'https://cdn.nyaitter.jp', client: givenClient, fetch: fetchImpl, cache } = options;
+    if (!source) {
+        throw new Error('source が必要です。<所有者>/<リポジトリ> の形で指定してください。');
+    }
+    const client = givenClient || createClient({ rawBase, fetch: fetchImpl, cache });
+    let currentVersionId = options.currentVersionId || null;
+
+    // 版の一覧。索引の順。各要素は { id, code, tag, commit, source, at, description }。
+    async function versions() {
+        const { entries } = await client.listVersions(source);
+        return entries;
+    }
+
+    // 最新の正式版。なければ null。
+    async function latest() {
+        return client.latestVersion(source);
+    }
+
+    // 現在の版と最新を比べる。
+    async function checkUpdate() {
+        const newest = await latest();
+        return {
+            current: currentVersionId,
+            latest: newest,
+            hasUpdate: Boolean(newest && newest.id !== currentVersionId),
+        };
+    }
+
+    // 版を取得して照合する。ref は版ID・版ID-ラベル・版コードのいずれか。
+    async function fetchVersion(ref, options) {
+        return client.fetchVersion(source, ref, options);
+    }
+
+    // 版の説明。配信サーバーの API から取得する。取得できなければ空を返す。
+    async function describe(versionId) {
+        try {
+            const fetcher = fetchImpl || globalThis.fetch;
+            if (!fetcher) return '';
+            const response = await fetcher(`${rawBase}/api/repos/${source}/versions/${versionId}`);
+            if (!response || !response.ok) return '';
+            const data = await response.json();
+            return String((data && data.description) || '').trim();
+        } catch (_) {
+            return '';
+        }
+    }
+
+    async function fetchLatest(options) {
+        const newest = await latest();
+        if (!newest) {
+            throw new Error(`正式版はまだありません: ${source}`);
+        }
+        return client.fetchVersion(source, newest.id, options);
+    }
+
+    function cacheName(versionId) {
+        return `nap-page:${String(source).toLowerCase()}:${versionId}`;
+    }
+
+    // 取得結果を Cache Storage へ格納する。キーは版の中のパスそのまま
+    // 構成員は nap_modules/<参照>/ の下。Service Worker からはこの
+    // キャッシュを版のファイルとして参照できる。
+    async function store(result, options = {}) {
+        if (typeof caches === 'undefined') {
+            throw new Error('Cache Storage が使えない環境です。');
+        }
+        const flat = {};
+        flattenInto(flat, '', result);
+        const storage = await caches.open(cacheName(result.versionId));
+        const entries = Object.entries(flat);
+        let done = 0;
+        for (const [rel, bytes] of entries) {
+            await storage.put(
+                rel,
+                new Response(bytes, { headers: { 'Content-Type': typeFor(rel) } }),
+            );
+            done += 1;
+            if (typeof options.onProgress === 'function') {
+                try {
+                    options.onProgress({ done, total: entries.length });
+                } catch (_) {}
+            }
+        }
+        return cacheName(result.versionId);
+    }
+
+    // 格納済みの版IDの一覧。
+    async function storedVersions() {
+        if (typeof caches === 'undefined') {
+            throw new Error('Cache Storage が使えない環境です。');
+        }
+        const prefix = `nap-page:${String(source).toLowerCase()}:`;
+        const keys = await caches.keys();
+        return keys
+            .filter((key) => key.startsWith(prefix))
+            .map((key) => key.slice(prefix.length));
+    }
+
+    // 指定した版を現在にして、他の版のキャッシュを消す。
+    async function activate(versionId) {
+        if (typeof caches === 'undefined') {
+            throw new Error('Cache Storage が使えない環境です。');
+        }
+        const keep = cacheName(versionId);
+        const prefix = `nap-page:${String(source).toLowerCase()}:`;
+        for (const key of await caches.keys()) {
+            if (key.startsWith(prefix) && key !== keep) {
+                await caches.delete(key);
+            }
+        }
+        currentVersionId = versionId;
+    }
+
+    return {
+        versions,
+        latest,
+        checkUpdate,
+        fetchVersion,
+        describe,
+        fetchLatest,
+        store,
+        storedVersions,
+        activate,
+        cacheName,
+        get currentVersionId() {
+            return currentVersionId;
+        },
+    };
+}
+
+export default { createNapPage };

package/client/package.json

@@ -0,0 +1 @@
+{"description":"NAP のクライアント向け取得ライブラリです。","name":"nap-client","private":true,"type":"module"}

package/lib/core.js

@@ -0,0 +1,166 @@
+'use strict';
+
+const crypto = require('crypto');
+
+const MANIFEST_NAME = 'version-manifest.json';
+const VERSIONS_BRANCH = 'nap/versions';
+const INDEX_BRANCH = 'nap/index';
+const ID_PATTERN = /^[0-9a-f]{64}$/;
+const LABEL_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+// TestVersion のラベル。git の参照名に使える形に限る。
+function validateLabel(label) {
+    if (
+        typeof label !== 'string' ||
+        label.length < 1 ||
+        label.length > 32 ||
+        !LABEL_PATTERN.test(label) ||
+        label.endsWith('.') ||
+        label.endsWith('.lock') ||
+        label.includes('..')
+    ) {
+        throw new Error(
+            `ラベルが不正です: ${label}。1〜32文字、英数字で始まり、使える文字は英数字と . _ - 。末尾の . と連続した .. は使えません`,
+        );
+    }
+    return label;
+}
+
+// 「<版ID>」または「<版ID>-<ラベル>」を分解する。版IDは前方一致の短縮でもよい。
+// 16進数には - が含まれないため、最初の - で一意に分かれる。
+function parseVersionRef(ref) {
+    if (typeof ref !== 'string' || ref.length === 0) {
+        throw new Error(`版の指定が不正です: ${ref}`);
+    }
+    const dash = ref.indexOf('-');
+    const prefix = dash === -1 ? ref : ref.slice(0, dash);
+    const tag = dash === -1 ? null : ref.slice(dash + 1);
+    if (!/^[0-9a-f]{1,64}$/.test(prefix)) {
+        throw new Error(`版の指定が不正です: ${ref}`);
+    }
+    if (tag !== null) validateLabel(tag);
+    return { prefix, tag };
+}
+
+// 版を指すタグ名。正式版は nap/<版ID>、TestVersion は nap/<版ID>-<ラベル>。
+function tagRefFor(id, tag) {
+    return tag ? `nap/${id}-${tag}` : `nap/${id}`;
+}
+
+function sha256Hex(buffer) {
+    return crypto.createHash('sha256').update(buffer).digest('hex');
+}
+
+function compareBytes(a, b) {
+    return Buffer.compare(Buffer.from(a, 'utf8'), Buffer.from(b, 'utf8'));
+}
+
+function hashLines(lines) {
+    const sorted = [...lines].sort(compareBytes);
+    return sha256Hex(Buffer.from(`${sorted.join('\n')}\n`, 'utf8'));
+}
+
+// パッケージIDは、自ファイルの `F <パス> <sha256>` 行だけから生成する。
+function packageIdOf(files) {
+    return hashLines(Object.entries(files).map(([rel, hash]) => `F ${rel} ${hash}`));
+}
+
+// 版IDは、自ファイルの F 行と、構成員の `P <組織ID>/<名前> <版ID>` 行から生成する。
+// libraries は { "<組織ID>/<名前>": "<版ID>" または { version } } の形で受ける。
+function versionIdOf(files, libraries) {
+    const lines = Object.entries(files).map(([rel, hash]) => `F ${rel} ${hash}`);
+    for (const [ref, lib] of Object.entries(libraries)) {
+        const version = typeof lib === 'string' ? lib : lib.version;
+        lines.push(`P ${ref} ${version}`);
+    }
+    return hashLines(lines);
+}
+
+// マニフェストの中身。版ID自身と日時は入れない。自己参照を避けるため。
+// libraries の各項目は { name, repo, version } を持つ。キーは決定的な並びにする。
+function manifestBuffer(files, libraries) {
+    const sortedFiles = {};
+    for (const rel of Object.keys(files).sort(compareBytes)) sortedFiles[rel] = files[rel];
+    const sortedLibs = {};
+    for (const ref of Object.keys(libraries).sort(compareBytes)) {
+        const lib = libraries[ref];
+        sortedLibs[ref] = { name: ref, repo: lib.repo, version: lib.version };
+    }
+    return Buffer.from(
+        `${JSON.stringify({ files: sortedFiles, libraries: sortedLibs }, null, 2)}\n`,
+        'utf8',
+    );
+}
+
+const CODE_PATTERN = /^[0-9a-z]{3,}$/;
+const CODE_ALPHABET = '0123456789abcdefghijklmnopqrstuvwxyz';
+
+// 版コードの形かどうか。版IDの完全な形とは重ならない。
+function isVersionCode(text) {
+    if (typeof text !== 'string' || !CODE_PATTERN.test(text)) return false;
+    return !/^[0-9a-f]{64}(-[A-Za-z0-9][A-Za-z0-9._-]*)?$/.test(text);
+}
+
+// 版コードは版IDから決める。同じ版にはいつも同じコードが割り当たる。
+// そのコードが使われていたら、桁を延ばして決める。
+function deriveVersionCode(versionId, used) {
+    const stream = BigInt(`0x${versionId}`).toString(CODE_ALPHABET.length);
+    for (let length = 3; length <= stream.length; length++) {
+        const code = stream.slice(0, length);
+        if (!used.has(code)) return code;
+    }
+    throw new Error('版コードを生成できませんでした。');
+}
+
+// ソースの指定は「<所有者>/<リポジトリ>」だけ。GitHub 前提。
+function isSourceSpec(source) {
+    if (typeof source !== 'string') return false;
+    const text = source.trim();
+    if (!text) return false;
+    const parts = text.split('/');
+    return parts.length === 2 && parts.every((part) => part.length > 0 && !/[\s:@]/.test(part));
+}
+
+function parseManifest(buffer) {
+    let manifest;
+    try {
+        manifest = JSON.parse(buffer.toString('utf8'));
+    } catch {
+        throw new Error('マニフェストが JSON として読めません。');
+    }
+    if (!manifest || typeof manifest !== 'object') {
+        throw new Error('マニフェストの形式が不正です。');
+    }
+    const files = manifest.files || {};
+    const libraries = manifest.libraries || {};
+    for (const [rel, hash] of Object.entries(files)) {
+        if (!ID_PATTERN.test(hash)) {
+            throw new Error(`マニフェストのファイルハッシュが不正です: ${rel}`);
+        }
+    }
+    for (const [ref, lib] of Object.entries(libraries)) {
+        if (!lib || lib.name !== ref || !isSourceSpec(lib.repo) || !ID_PATTERN.test(lib.version || '')) {
+            throw new Error(`マニフェストの構成員が不正です: ${ref}`);
+        }
+    }
+    return { files, libraries };
+}
+
+module.exports = {
+    MANIFEST_NAME,
+    VERSIONS_BRANCH,
+    INDEX_BRANCH,
+    ID_PATTERN,
+    validateLabel,
+    parseVersionRef,
+    tagRefFor,
+    sha256Hex,
+    compareBytes,
+    packageIdOf,
+    versionIdOf,
+    manifestBuffer,
+    parseManifest,
+    isSourceSpec,
+    isVersionCode,
+    deriveVersionCode,
+};

package/lib/declaration.js

@@ -0,0 +1,89 @@
+'use strict';
+
+const DECLARATION_FILE = 'nap.json';
+const NAME_PATTERN = /^[a-z0-9][a-z0-9._-]*$/;
+const ID_PATTERN = /^[0-9a-f]{64}$/;
+
+function parseComposition(raw, where) {
+    if (raw === undefined) return null;
+    if (!Array.isArray(raw) || raw.length === 0) {
+        throw new Error(`${where}.composition には構成員が1件以上必要です。`);
+    }
+    const seen = new Set();
+    return raw.map((entry, index) => {
+        const at = `${where}.composition[${index}]`;
+        const ref = typeof entry === 'string' ? entry : entry && entry.name;
+        const version = typeof entry === 'string' ? null : entry && entry.version;
+        // 構成員の参照は「<組織ID>/<パッケージ名>」で、組織IDは省略できない。
+        const slash = typeof ref === 'string' ? ref.indexOf('/') : -1;
+        const org = slash > 0 ? ref.slice(0, slash) : '';
+        const name = slash > 0 ? ref.slice(slash + 1) : '';
+        if (!NAME_PATTERN.test(org) || !NAME_PATTERN.test(name)) {
+            throw new Error(`${at} のパッケージ参照が不正です。<組織ID>/<パッケージ名> の形で書いてください。`);
+        }
+        if (seen.has(ref)) {
+            throw new Error(`構成員が重複しています: ${ref}`);
+        }
+        seen.add(ref);
+        if (version !== null && version !== undefined) {
+            if (typeof version !== 'string' || !ID_PATTERN.test(version)) {
+                throw new Error(`${at}.version は版IDで書いてください。版IDは16進数64桁です。`);
+            }
+            return { ref, org, name, version };
+        }
+        return { ref, org, name, version: null };
+    });
+}
+
+// 宣言は1リポジトリ1パッケージのフラットな形式だけを受ける。
+// 旧形式の packages 配列は互換読みせず、明確なエラーにする。
+function parseDeclaration(text) {
+    let doc;
+    try {
+        doc = JSON.parse(text);
+    } catch {
+        throw new Error(`${DECLARATION_FILE} が JSON として読めません。`);
+    }
+    if (!doc || typeof doc !== 'object' || Array.isArray(doc)) {
+        throw new Error(`${DECLARATION_FILE} の形式が不正です。`);
+    }
+    if ('packages' in doc) {
+        throw new Error(
+            `${DECLARATION_FILE} の旧形式 packages 配列は使えません。` +
+                'name／include／composition をトップレベルに書いてください。',
+        );
+    }
+    if (typeof doc.name !== 'string' || !NAME_PATTERN.test(doc.name)) {
+        throw new Error(
+            `${DECLARATION_FILE}.name が不正です。小文字の英数字と . _ - で始まる名前を使ってください。`,
+        );
+    }
+    if (
+        !Array.isArray(doc.include) ||
+        doc.include.length === 0 ||
+        doc.include.some((pattern) => typeof pattern !== 'string' || pattern.length === 0)
+    ) {
+        throw new Error(`${DECLARATION_FILE}.include には対象ファイルの指定が1件以上必要です。`);
+    }
+    for (const pattern of doc.include) {
+        const body = pattern.startsWith('!') ? pattern.slice(1) : pattern;
+        if (body.startsWith('/') || body.split('/').includes('..')) {
+            throw new Error(
+                `${DECLARATION_FILE}.include の指定がリポジトリの外を指しています: ${pattern}`,
+            );
+        }
+    }
+    const composition = parseComposition(doc.composition, DECLARATION_FILE);
+    if (composition) {
+        for (const member of composition) {
+            if (member.name === doc.name) {
+                throw new Error(
+                    `構成員に自分自身は書けません。宣言したパッケージは自動で版に含まれます: ${member.ref}`,
+                );
+            }
+        }
+    }
+    return { name: doc.name, include: doc.include, composition };
+}
+
+module.exports = { DECLARATION_FILE, NAME_PATTERN, parseDeclaration };

package/lib/fork.js

@@ -0,0 +1,147 @@
+'use strict';
+
+// nap fork: パッケージのフォークを nap_modules へ置く。フォークはリポジトリの複製。
+// パッケージ自体が Git リポジトリであることを利用し、clone した作業ツリーを
+// そのまま導入済みの場所に置く。導入済みなら置き換え、未導入なら導入になる。
+// 以後、その場所は通常の Git リポジトリとして編集でき、nap get では上書きされず、
+// nap publish では現在の内容が版へ埋め込まれる。
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+const { sha256Hex } = require('./core');
+const { parseGetTarget, dependencyRefFor, recordDependency, MODULES_DIR } = require('./get');
+const { readIndexAt } = require('./read');
+const { INDEX_BRANCH } = require('./core');
+
+function git(args, options = {}) {
+    return execFileSync('git', args, { encoding: 'utf8', ...options });
+}
+
+// ソースから clone 先の URL を作る。ソースは「<所有者>/<リポジトリ>」の形。
+function cloneUrlFor(repo) {
+    return `https://github.com/${repo}.git`;
+}
+
+function isForkDir(dir) {
+    return fs.existsSync(path.join(dir, '.git'));
+}
+
+// 導入済みコピーが導入時の内容から変わっているか。フォークではないものが対象。
+function installedDiverged(dir) {
+    const manifestPath = path.join(dir, 'version-manifest.json');
+    if (!fs.existsSync(manifestPath)) return true;
+    let manifest;
+    try {
+        manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    } catch {
+        return true;
+    }
+    for (const [rel, hash] of Object.entries(manifest.files || {})) {
+        const filePath = path.join(dir, rel);
+        if (!fs.existsSync(filePath)) return true;
+        if (sha256Hex(fs.readFileSync(filePath)) !== hash) return true;
+    }
+    return false;
+}
+
+async function fork(specText) {
+    const cwd = process.cwd();
+    const declarationPath = path.join(cwd, 'nap.json');
+    if (!fs.existsSync(declarationPath)) {
+        throw new Error(
+            'nap.json がありません。フォークは、プロジェクトのフォルダで実行してください。',
+        );
+    }
+    const { repo, ref } = parseGetTarget(specText);
+    const depRef = dependencyRefFor(repo);
+    const targetDir = path.join(cwd, MODULES_DIR, depRef);
+    if (isForkDir(targetDir)) {
+        throw new Error(`既にフォークされています: ${depRef}。場所: ${targetDir}`);
+    }
+    if (fs.existsSync(targetDir) && installedDiverged(targetDir)) {
+        throw new Error(
+            '導入済みのコピーが変更されています。フォークで置き換えると変更が失われるため止めました。',
+        );
+    }
+
+    // 版を確定する。取得ライブラリで実在を確かめる。
+    const { createClient } = await import('../client/nap-client.js');
+    const client = createClient({ rawBase: process.env.NAP_RAW_BASE || undefined });
+    let versionId;
+    let label = null;
+    if (ref === null) {
+        const latest = await client.latestVersion(repo);
+        if (!latest) throw new Error(`正式版はまだありません: ${repo}`);
+        versionId = latest.id;
+    } else {
+        const resolved = await client.fetchVersion(repo, ref);
+        versionId = resolved.versionId;
+        label = resolved.tag || null;
+    }
+
+    const tmpDir = `${targetDir}.fork-tmp`;
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+    try {
+        git(['clone', '--quiet', cloneUrlFor(repo), tmpDir], { stdio: 'inherit' });
+        if (ref !== null) {
+            // 基点は、版の出典コミットか、版のツリーにする。出典コミットは辿れる場合。
+            const tagRef = label ? `nap/${versionId}-${label}` : `nap/${versionId}`;
+            // 出典は索引に記録されている。出典は発行の対象だったコミット。
+            // clone した側の索引から引き、コミットが手元にあればそれを基点にする。
+            const { entries } = readIndexAt(tmpDir, `refs/remotes/origin/${INDEX_BRANCH}`);
+            const hit = entries.find(
+                (e) => e.id === versionId && (e.tag || null) === (label || null),
+            );
+            let source = null;
+            if (hit && hit.source) {
+                try {
+                    git(['rev-parse', '--verify', '--quiet', `${hit.source}^{commit}`], {
+                        cwd: tmpDir,
+                    });
+                    source = hit.source;
+                } catch {
+                    source = null;
+                }
+            }
+            git(['checkout', '--quiet', source || `refs/tags/${tagRef}`], { cwd: tmpDir });
+            if (!fs.existsSync(path.join(tmpDir, 'nap.json'))) {
+                // 宣言が版のツリーに無い場合は、既定ブランチのものを持ってくる。
+                let declaration;
+                try {
+                    declaration = git(['show', 'origin/HEAD:nap.json'], { cwd: tmpDir });
+                } catch {
+                    throw new Error(
+                        'パッケージの宣言 nap.json が、版のツリーにも既定ブランチにもありません。',
+                    );
+                }
+                fs.writeFileSync(path.join(tmpDir, 'nap.json'), declaration);
+                git(['add', 'nap.json'], { cwd: tmpDir });
+                git(['commit', '--quiet', '-m', 'fork: add nap.json from default branch'], {
+                    cwd: tmpDir,
+                    env: {
+                        ...process.env,
+                        GIT_AUTHOR_NAME: 'nap',
+                        GIT_AUTHOR_EMAIL: 'nap@localhost',
+                        GIT_COMMITTER_NAME: 'nap',
+                        GIT_COMMITTER_EMAIL: 'nap@localhost',
+                    },
+                });
+            }
+        }
+        fs.mkdirSync(path.dirname(targetDir), { recursive: true });
+        fs.rmSync(targetDir, { recursive: true, force: true });
+        fs.renameSync(tmpDir, targetDir);
+    } catch (error) {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+        throw error;
+    }
+
+    const text = fs.readFileSync(declarationPath, 'utf8');
+    fs.writeFileSync(declarationPath, recordDependency(text, depRef, versionId));
+    console.log(`フォーク: ${depRef} = ${versionId}`);
+    console.log(`場所: ${targetDir}`);
+    console.log('origin は元のリポジトリです。自分の場所へ出すときは差し替えてください。');
+}
+
+module.exports = { fork, cloneUrlFor, isForkDir };