@nyaitter/nap 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,142 @@
-# Temporary Holding Version
+# NAP
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+リポジトリに版を付けて公開し、公開された版を取り寄せるためのツールです。
+
+## インストール
+
+```bash
+npm install -g @nyaitter/nap
+```
+
+npx からも使えます。
+
+```console
+$ npx @nyaitter/nap publish
+```
+
+## 使い始める
+
+### 版を作る
+
+リポジトリのルートに nap.json を作ります。
+
+```console
+$ nap init
+```
+
+nap.json は次の形です。
+
+```json
+{
+  "name": "nyaitter-client",
+  "include": ["**"],
+  "composition": ["nyaitter/nyaitter.js", "nyaitter/nyaitterui", "nyaitter/nyaitterime"]
+}
+```
+
+発行します。
+
+```console
+$ nap publish
+```
+
+今のコミットの内容が版になります。同じ内容で再実行しても、新しい版は作られません。
+
+指定できるもの:
+
+- --ref <コミット|ブランチ>: 対象のコミットを変える
+- --remote <リモート>: 公開先を変える。既定は origin
+- --libraries <file.json>: 一緒に使うパッケージの入手先を渡す
+- --test <ラベル>: 開発中の版として発行する
+- --no-push: 版を作るだけで、公開しない
+- --message <説明>: 版の説明を付ける。説明は nap show で見られる
+
+--libraries のファイルは次の形です。版を固定したいときは version に版IDを書きます。
+
+```json
+{
+  "nyaitter/nyaitter.js": { "repo": "Nyaitter/Nyaitter.js", "source": "../nyaitter.js" },
+  "nyaitter/nyaitterui": { "repo": "Nyaitter/NyaitterUI", "source": "../nyaitter-ui" }
+}
+```
+
+### 版を取り寄せる
+
+```console
+$ nap get Nyaitter/Client
+$ nap get Nyaitter/Client/<版ID>
+$ nap get Nyaitter/Client/<版コード>
+```
+
+指定がなければ、最新の正式版です。取り寄せた内容は照合してから置きます。置き場所は --out <ディレクトリ> で指定できます。既定はリポジトリ名のフォルダです。一緒に使うパッケージも一緒に置かれます。
+
+### プロジェクトへ導入する
+
+nap.json のあるフォルダで、--out を付けずに実行すると導入になります。
+
+```console
+$ nap get Nyaitter/Nyaitter.js
+```
+
+パッケージは nap_modules の中に置かれ、版まで nap.json の composition に記録されます。導入したパッケージは相対パスでそのまま使えます。nap_modules は Git の追跡対象にしません。
+
+nap get を指定なしで実行すると、記録されたものをすべて導入します。
+
+発行するときは、記録されたパッケージが版に含まれます。版は単独で使えます。
+
+## 版を調べる
+
+```console
+$ nap list
+$ nap show <版ID>
+$ nap show <版コード>
+```
+
+nap list は版の一覧を出します。nap show は、指定がなければ最新の正式版を出します。版IDは先頭だけでも指定できます。
+
+## パッケージを探す
+
+```console
+$ nap search client
+```
+
+nap.json を持つリポジトリを探します。GITHUB_TOKEN の設定が必要です。
+
+## フォーク
+
+```console
+$ nap fork Nyaitter/Nyaitter.js
+```
+
+パッケージを手元で直したいときは nap fork を使います。元のリポジトリを複製したものが nap_modules の中に置かれ、普通の Git リポジトリとして編集できます。nap get では上書きされません。
+
+ルートで nap publish を実行すると、フォークの今の内容が版に含まれます。フォークに変更があれば、一緒に発行するか確認します。
+
+## 取り除く
+
+```console
+$ nap remove Nyaitter/Nyaitter.js
+```
+
+導入したパッケージと nap.json の記録を取り除きます。対象がフォークのときは、作業内容が失われるため確認します。--yes を付けると確認を省けます。
+
+## 開発中の版
+
+開発中の版は TestVersion と呼びます。
+
+```console
+$ nap publish --test <ラベル>
+$ nap get Nyaitter/Client/<版ID>-<ラベル>
+```
+
+誰でも取得して試せますが、最新の版としては選ばれません。同じ内容を --test なしで発行すると、そのまま正式版になります。
+
+## 非公開の版
+
+非公開の版はありません。正式に出す前に試してもらいたいときは、開発中の版を使ってください。版そのものを非公開にしたいときは、プライベートリポジトリなど、置き場所側の仕組みを使ってください。
+
+## ドキュメント
+
+- [仕様](./SPEC.md)
+- [取得ライブラリ](./client/README.md)
+- [配信サーバー](./cdn/README.md)

package/cli.js

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+'use strict';
+
+const { publish } = require('./lib/publish');
+const { list, show } = require('./lib/inspect');
+const { get } = require('./lib/get');
+const { search } = require('./lib/search');
+
+function usage() {
+    console.error('使い方:');
+    console.error('  nap publish [<リポジトリ>] [--ref <コミット|ブランチ>] [--remote <リモート>] [--libraries <file.json>] [--test <ラベル>] [--message <説明>] [--no-push]\n  nap init [<名前>]');
+    console.error('  nap list [<リポジトリ>] [--remote <リモート>]');
+    console.error('  nap show [<版ID>] [--repo <リポジトリ>] [--remote <リモート>]');
+    console.error('  nap get [<指定>] [--out <出力先>]');
+    console.error('  nap fork <指定>\n  nap remove <指定> [--yes]');
+    console.error('  nap search [キーワード...] [--limit <件数>]');
+    console.error('publish は、リポジトリの中で実行するとそのリポジトリを対象にします。');
+}
+
+function parseOptions(args, allowed) {
+    const positional = [];
+    const options = {};
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg.startsWith('--')) {
+            const key = arg.slice(2);
+            if (!allowed.includes(key)) return { error: `不明なオプションです: ${arg}` };
+            const value = args[++i];
+            if (value === undefined) return { error: `オプションには値が必要です: ${arg}` };
+            options[key] = value;
+        } else {
+            positional.push(arg);
+        }
+    }
+    return { positional, options };
+}
+
+async function main(argv) {
+    const [command, ...rest] = argv;
+    if (command === 'publish') {
+        const noPush = rest.includes('--no-push');
+        const publishArgs = rest.filter((a) => a !== '--no-push');
+        const { positional, options, error } = parseOptions(publishArgs, [
+            'ref',
+            'remote',
+            'libraries',
+            'chunk-size',
+            'test',
+            'message',
+        ]);
+        if (error || positional.length > 1) {
+            if (error) console.error(error);
+            usage();
+            return 2;
+        }
+        const chunkSize =
+            options['chunk-size'] !== undefined
+                ? Number(options['chunk-size'])
+                : Number(process.env.NAP_CHUNK_SIZE || 200);
+        await publish(positional[0], {
+            ref: options.ref,
+            remote: options.remote,
+            libraries: options.libraries,
+            chunkSize,
+            test: options.test,
+            message: options.message,
+            noPush,
+        });
+        return 0;
+    }
+    if (command === 'list') {
+        const { positional, options, error } = parseOptions(rest, ['remote']);
+        if (error || positional.length > 1) {
+            if (error) console.error(error);
+            usage();
+            return 2;
+        }
+        await list(positional[0], { remote: options.remote });
+        return 0;
+    }
+    if (command === 'show') {
+        const { positional, options, error } = parseOptions(rest, ['repo', 'remote']);
+        if (error || positional.length > 1) {
+            if (error) console.error(error);
+            usage();
+            return 2;
+        }
+        await show(positional[0], { repo: options.repo, remote: options.remote });
+        return 0;
+    }
+    if (command === 'init') {
+        if (rest.length > 1 || (rest.length === 1 && rest[0].startsWith('-'))) {
+            usage();
+            return 2;
+        }
+        const { init } = require('./lib/init');
+        await init(rest[0]);
+        return 0;
+    }
+
+    if (command === 'get') {
+        const { positional, options, error } = parseOptions(rest, ['out']);
+        if (error || positional.length > 1) {
+            if (error) console.error(error);
+            usage();
+            return 2;
+        }
+        await get(positional[0], { out: options.out });
+        return 0;
+    }
+    if (command === 'fork') {
+        const { fork } = require('./lib/fork');
+        const { positional, options, error } = parseOptions(rest, []);
+        if (error || positional.length !== 1 || Object.keys(options).length > 0) {
+            if (error) console.error(error);
+            usage();
+            return 2;
+        }
+        await fork(positional[0]);
+        return 0;
+    }
+    if (command === 'remove') {
+        const yes = rest.includes('--yes');
+        const removeArgs = rest.filter((a) => a !== '--yes');
+        if (removeArgs.length !== 1) {
+            usage();
+            return 2;
+        }
+        const { remove } = require('./lib/remove');
+        await remove(removeArgs[0], { yes });
+        return 0;
+    }
+
+    if (command === 'search') {
+        const { positional, options, error } = parseOptions(rest, ['limit']);
+        if (error) {
+            console.error(error);
+            usage();
+            return 2;
+        }
+        const limit = options.limit !== undefined ? Number(options.limit) : 20;
+        await search(positional, { limit });
+        return 0;
+    }
+    usage();
+    return 2;
+}
+
+main(process.argv.slice(2)).then(
+    (code) => {
+        process.exitCode = code;
+    },
+    (error) => {
+        console.error(error instanceof Error ? error.message : error);
+        process.exitCode = 1;
+    },
+);

package/client/README.md

@@ -0,0 +1,135 @@
+# nap-client
+
+NAP の版を取得するライブラリです。単一ファイルで、追加のパッケージは要りません。ブラウザと Node の両方で使えます。
+
+## createClient
+
+```js
+import { createClient, createMemoryCache } from './nap-client.js';
+
+const client = createClient({
+    cache: createMemoryCache(),
+});
+```
+
+指定できるもの:
+
+- rawBase: 取得先の基底 URL。nap-cdn のような配信サーバーを使うときに指定する
+- cache: get と put を持つオブジェクト。省略するとメモリ上のものになる
+- fetch: 取得に使う fetch。省略すると標準の fetch を使う
+
+取得先は、各呼び出しに渡す入手先から決まります。入手先の形は所有者とリポジトリ名を並べたもので、対象は GitHub のリポジトリです。
+
+## listVersions
+
+```js
+const { total, entries } = await client.listVersions(repo, { latestOnly: true });
+```
+
+版の一覧を返します。戻り値は total と entries です。entries は発行順で、各件は id と commit と at と tag を持ちます。tag は正式版では null、開発中の版ではそのラベルです。開発中の版は TestVersion と呼びます。
+
+latestOnly に true を指定すると、返る entries は最後の一まとまり分だけになります。total は全体の件数のままです。latestOnly を指定しないときは、全件が返ります。
+
+## latestVersion
+
+```js
+const latest = await client.latestVersion(repo);
+```
+
+最新の正式版を1件返します。形は id と commit と at と tag です。tag は null です。開発中の版は対象になりません。正式版が無ければ null を返します。
+
+## getManifest
+
+```js
+const manifest = await client.getManifest(repo, ref);
+```
+
+版のマニフェストを返します。ref は版ID、または版IDとラベルを並べた形です。ラベル付きは開発中の版を指します。内容が版IDと合わなければ例外になります。
+
+## getManifests
+
+```js
+const manifests = await client.getManifests(repo, ref);
+```
+
+マニフェストだけを、構成員まで含めて返します。ファイルの中身は取得しません。戻り値は versionId と tag と files と libraries で、libraries の各値も同じ形です。
+
+## fetchFile
+
+```js
+const bytes = await client.fetchFile(repo, ref, path);
+```
+
+版に属するファイル1点を取得し、バイト列を返します。照合は行わないので、呼び出し側でマニフェストと照合してください。
+
+## parseSpec と fetchSpec と getSpecManifests
+
+パッケージは3つの要素で指定します。所有者とリポジトリと版です。
+
+```js
+const parsed = parseSpec('Nyaitter/Client/<版ID>');
+const version = await client.fetchSpec('Nyaitter/Client/<版ID>');
+const manifests = await client.getSpecManifests('Nyaitter/Client/<版コード>');
+```
+
+parseSpec は指定を repo と ref と id と tag に分けます。対象は版IDだけです。fetchSpec と getSpecManifests では、版の部分に版コードも使えます。版コードは発行のときに付く短いコードです。fetchSpec は fetchVersion と同じものを返し、getSpecManifests は getManifests と同じものを返します。
+
+## fetchVersion
+
+```js
+const version = await client.fetchVersion(repo, ref);
+```
+
+版のファイルすべてを取得します。ref は版ID、または版IDとラベルを並べた形です。開発中の版を使うときはラベルまで書きます。
+
+第3引数に onProgress を渡すと、取得の進み具合が phase と fetched と cached と total の形で通知されます。phase は download と unpack のどちらかです。
+
+rawBase を渡したクライアントは、配信サーバーの専用 API で版の一覧を取り、版のファイルは ZIP で一括取得します。ZIP の取得や展開に失敗したときは、ファイルごとの取得に切り替わります。ZIP の取得中は、進捗の bytes と bytesTotal に受信バイト数と全体のバイト数が入ります。
+
+戻り値は versionId と tag と files と libraries と stats です。
+
+- versionId: 版ID。ラベルは含まない
+- tag: 正式版では null、開発中の版ではそのラベル
+- files: パスとバイト列の対応。バイト列は Uint8Array
+- libraries: 構成員ごとの、同じ形の戻り値
+- stats: fetched と cached と total。取得した件数と、手元で済んだ件数と、全体の件数
+
+取得したファイルはマニフェストと照合します。照合が1つでも失敗したら例外になり、一部だけの結果は返りません。構成員も同じように照合します。
+
+## NAP-Page
+
+nap-page.js は、ページを NAP の版で管理するライブラリです。更新の確認と、版の取得と、ブラウザへの保存をします。
+
+```js
+import { createNapPage } from './nap-page.js';
+
+const page = createNapPage({
+    source: '<所有者>/<リポジトリ>',
+    rawBase: 'https://cdn.nyaitter.jp',
+    currentVersionId: '<今の版ID>',
+});
+
+const { hasUpdate, latest } = await page.checkUpdate();
+if (hasUpdate) {
+    const result = await page.fetchVersion(latest.id);
+    await page.store(result);
+    await page.activate(latest.id);
+}
+```
+
+source は必須です。rawBase と currentVersionId は任意です。rawBase の既定は https://cdn.nyaitter.jp です。
+
+使える呼び出し:
+
+- versions: 版の一覧を返す
+- latest: 最新の正式版を返す
+- checkUpdate: 更新があるかと最新の正式版を返す
+- fetchVersion: 版を取得する
+- describe: 版の説明を返す。取得できなければ空
+- fetchLatest: 最新の正式版を取得する
+- store: 取得した版をブラウザに保存する
+- storedVersions: 保存済みの版を返す
+- activate: 指定した版を有効にし、他の版の保存を消す
+- cacheName: 版の保存名を返す
+
+store はブラウザの Cache Storage を使います。使えない環境ではエラーになります。