kairos-lang 1.0.0

package/dist/cli.d.ts

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+import type { ExternalResolver } from './index.ts';
+import type { ResultAnnotation, CoverageEntry } from './eval.ts';
+/** CLI の結果表面。人間表示（renderHuman）と --json はこの一つの器から出す——両表示の乖離を封じる */
+export interface CliReport {
+    command: 'list' | 'next';
+    version: string;
+    tz: string;
+    from: string;
+    to: string;
+    requested?: number;
+    found?: number;
+    horizonYears?: number;
+    results: {
+        source: string;
+        dates: string[];
+        points: number[];
+        annotations: ResultAnnotation[];
+    }[];
+    coverage: CoverageEntry[];
+    warnings: string[];
+}
+/** 実行 tz の今日（市民日付）。時計読みは CLI 境界のみ——言語・評価は不変に決定的 */
+export declare function todayIn(tz: string): string;
+interface CmdOpts {
+    from: string;
+    to?: string;
+    tz?: string;
+    resolve?: ExternalResolver;
+}
+/** --supply の静的束から external 解決子を作る（ADR-46 の RunOptions.resolve へ渡す形）。
+ *  形: {キー: {dates|instants, covering, asof [, labels]}}——キーは束縛名または "premise.束縛名"
+ *  （premise 修飾が優先。source は named-arg 上書きで多対一になり得るためキーにしない）。
+ *  ここでは JSON の形だけを検査する——覆域の包含・昇順・実在日などの供給契約 12 種は
+ *  評価器側の検査（external の統治）がそのまま掛かる。 */
+export declare function supplyResolver(raw: unknown, origin: string): ExternalResolver;
+/** list: 範囲 [from, to) の全発火＋註釈＋被覆サマリ */
+export declare function cmdList(source: string, o: CmdOpts & {
+    to: string;
+}): CliReport;
+/** next: from 以降の次の N 発火。窓を 1 年から倍々に広げて探索し（上限＝horizon 年）、
+ *  見つかったら [from, 最終発火日の翌日) で確定再評価——註釈・残走路が答えの範囲と整合する。
+ *  地平線まで探して不足なら見つかった分を返す（found < requested）。 */
+export declare function cmdNext(source: string, o: CmdOpts & {
+    n: number;
+    horizonYears: number;
+}): CliReport;
+/** 表示言語（--lang en で定型出力の枠組みだけ英語化。評価器メッセージ＝エラー・註釈文は
+ * 日本語が正のまま・--json は言語中立——線引きは en/playground と同一） */
+export type CliLang = 'ja' | 'en';
+/** 人間向け表示（stdout 行列）。--json と同じ CliReport から出す */
+export declare function renderHuman(rep: CliReport, lang?: CliLang): string[];
+/** 入口（SEA ビルドのエントリスタブからも呼ぶ）。戻り値＝終了コード */
+export declare function main(argv: string[]): number;
+export {};

package/dist/cli.js

@@ -0,0 +1,309 @@
+#!/usr/bin/env node
+// Kairos CLI — サブコマンド: list（範囲の点列）・next（次の N 発火）
+// 使い方（kairos ＝ node src/cli.ts。配布名は 1.0 で npm bin / SEA に載せる）:
+//   kairos list [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--tz Zone] [--json] <file.kairos>
+//   kairos next [-n 件数] [--from YYYY-MM-DD] [--horizon 年数] [--tz Zone] [--json] <file.kairos>
+// サブコマンド省略時（先頭引数がファイル）は list——旧形式の実行例を全て生かす後方互換。
+// 終了コード: 0=成功・1=エラー・2=next が地平線内に要求件数を見つけられず（部分結果は表示する）。
+// external() は --supply <file.json> の静的束で解決できる（supplyResolver → RunOptions.resolve）。
+// --supply 無しでの解決は供給エラー（ADR-46 の既定どおり）。
+import { readFileSync, realpathSync } from 'node:fs';
+import { parseArgs } from 'node:util';
+import { fileURLToPath } from 'node:url';
+import { run, formatAnnotation, KairosError, SupplyError } from "./index.js";
+// 実装版（JSON 出力の版規律）。SEA 束ね時は build 側でリテラルへ差し替え（index.ts の stdlib と同型）
+const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+/** 実行 tz の今日（市民日付）。時計読みは CLI 境界のみ——言語・評価は不変に決定的 */
+export function todayIn(tz) {
+    return new Intl.DateTimeFormat('en-CA', { timeZone: tz, year: 'numeric', month: '2-digit', day: '2-digit' }).format(new Date());
+}
+// 日付字面の算術（純グレゴリオ・Date.UTC の正規化に委ねる。2/29+1y 等は run() 側の
+// civilDayStart が翌日に正規化＝評価範囲の端としては安全）
+const partsOf = (s) => {
+    const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(s);
+    if (!m)
+        throw new KairosError(`日付は YYYY-MM-DD: ${s}`);
+    return [+m[1], +m[2], +m[3]];
+};
+const addYears = (s, k) => {
+    const [y, mo, d] = partsOf(s);
+    return `${String(y + k).padStart(4, '0')}-${String(mo).padStart(2, '0')}-${String(d).padStart(2, '0')}`;
+};
+const addDays = (s, n) => {
+    const [y, mo, d] = partsOf(s);
+    return new Date(Date.UTC(y, mo - 1, d + n)).toISOString().slice(0, 10);
+};
+/** --supply の静的束から external 解決子を作る（ADR-46 の RunOptions.resolve へ渡す形）。
+ *  形: {キー: {dates|instants, covering, asof [, labels]}}——キーは束縛名または "premise.束縛名"
+ *  （premise 修飾が優先。source は named-arg 上書きで多対一になり得るためキーにしない）。
+ *  ここでは JSON の形だけを検査する——覆域の包含・昇順・実在日などの供給契約 12 種は
+ *  評価器側の検査（external の統治）がそのまま掛かる。 */
+export function supplyResolver(raw, origin) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        throw new KairosError(`--supply は {束縛名: {dates|instants, covering, asof}} の JSON オブジェクト: ${origin}`);
+    }
+    const table = new Map();
+    for (const [key, v] of Object.entries(raw)) {
+        const where = `--supply ${origin} の "${key}"`;
+        if (typeof v !== 'object' || v === null || Array.isArray(v)) {
+            throw new KairosError(`${where} は {dates|instants, covering, asof} のオブジェクト`);
+        }
+        const e = v;
+        const hasDates = 'dates' in e, hasInstants = 'instants' in e;
+        if (hasDates === hasInstants) {
+            throw new KairosError(`${where}: dates / instants はどちらか一方（wire は宣言の kind と評価器が照合する）`);
+        }
+        if (typeof e.covering !== 'string' || e.covering === '')
+            throw new KairosError(`${where}: covering（文字列）が必須`);
+        if (typeof e.asof !== 'string' || e.asof === '')
+            throw new KairosError(`${where}: asof（文字列）が必須`);
+        if (hasDates && !(Array.isArray(e.dates) && e.dates.every(d => typeof d === 'string'))) {
+            throw new KairosError(`${where}: dates は "YYYY-MM-DD" の文字列配列`);
+        }
+        if (hasInstants && !(Array.isArray(e.instants) && e.instants.every(n => typeof n === 'number'))) {
+            throw new KairosError(`${where}: instants は epoch ミリ秒の数値配列（CliReport の points と同じ規約）`);
+        }
+        if ('labels' in e && !(Array.isArray(e.labels) && e.labels.every(l => typeof l === 'string'))) {
+            throw new KairosError(`${where}: labels は文字列配列`);
+        }
+        table.set(key, {
+            ...(hasDates ? { dates: e.dates } : { instants: e.instants }),
+            covering: e.covering,
+            asof: e.asof,
+            ...('labels' in e ? { labels: e.labels } : {}),
+        });
+    }
+    return (premise, binding) => {
+        const hit = table.get(`${premise}.${binding}`) ?? table.get(binding);
+        if (!hit) {
+            throw new SupplyError(`供給エラー: --supply ${origin} に ${binding} がない`
+                + `（キーは束縛名または "premise.束縛名"——ここでは "${premise}.${binding}"）`);
+        }
+        return hit;
+    };
+}
+function toReport(command, r, o, next) {
+    return {
+        command,
+        version: VERSION,
+        tz: o.tz ?? 'Asia/Tokyo',
+        from: o.from,
+        to: o.to,
+        ...(next ? { requested: next.requested, found: next.found, horizonYears: next.horizonYears } : {}),
+        results: r.results.map(res => ({
+            source: res.source, dates: res.dates, points: res.points, annotations: res.annotations,
+        })),
+        coverage: r.coverage,
+        warnings: r.warnings,
+    };
+}
+/** list: 範囲 [from, to) の全発火＋註釈＋被覆サマリ */
+export function cmdList(source, o) {
+    return toReport('list', run(source, { from: o.from, to: o.to,
+        ...(o.tz ? { tz: o.tz } : {}), ...(o.resolve ? { resolve: o.resolve } : {}) }), o);
+}
+/** next: from 以降の次の N 発火。窓を 1 年から倍々に広げて探索し（上限＝horizon 年）、
+ *  見つかったら [from, 最終発火日の翌日) で確定再評価——註釈・残走路が答えの範囲と整合する。
+ *  地平線まで探して不足なら見つかった分を返す（found < requested）。 */
+export function cmdNext(source, o) {
+    const meta = { requested: o.n, found: 0, horizonYears: o.horizonYears };
+    const runOpts = { ...(o.tz ? { tz: o.tz } : {}), ...(o.resolve ? { resolve: o.resolve } : {}) };
+    let years = Math.min(1, o.horizonYears);
+    for (;;) {
+        const to = addYears(o.from, years);
+        const r = run(source, { from: o.from, to, ...runOpts });
+        if (r.results.length === 0)
+            throw new KairosError('本体式がない');
+        if (r.results.length > 1)
+            throw new KairosError(`next は本体式 1 つのファイル向け（${r.results.length} 式ある——list を使うか式を 1 つに）`);
+        const found = r.results[0];
+        if (found.dates.length >= o.n) {
+            // 確定再評価: 右端＝N 発火目の翌市民日（同日複数瞬間の切り落としは slice で）
+            const toFinal = addDays(found.dates[o.n - 1].slice(0, 10), 1);
+            const rf = run(source, { from: o.from, to: toFinal, ...runOpts });
+            const res = rf.results[0];
+            res.dates = res.dates.slice(0, o.n);
+            res.points = res.points.slice(0, o.n);
+            return toReport('next', rf, { ...o, to: toFinal }, { ...meta, found: o.n });
+        }
+        if (years >= o.horizonYears) {
+            return toReport('next', r, { ...o, to }, { ...meta, found: found.dates.length });
+        }
+        years = Math.min(years * 2, o.horizonYears);
+    }
+}
+const CLI_STRINGS = {
+    ja: {
+        exprHead: (i, n) => `# 式 ${i}（${n} 件）`,
+        coverageHead: '# 被覆サマリ',
+        concluded: '（完結主張）',
+        runway: (d) => `残走路 ${d === null ? '∞' : `${d} 日`}`,
+        warning: (w) => `警告: ${w}`,
+        horizonShort: (rep) => `⚠ 地平線 ${rep.horizonYears} 年以内の発火は ${rep.found} 件（要求 ${rep.requested} 件）`,
+    },
+    en: {
+        exprHead: (i, n) => `# expression ${i} (${n} point${n === 1 ? '' : 's'})`,
+        coverageHead: '# coverage summary',
+        concluded: '(concluded)',
+        runway: (d) => `runway ${d === null ? '∞' : `${d} day${d === 1 ? '' : 's'}`}`,
+        warning: (w) => `warning: ${w}`,
+        horizonShort: (rep) => `⚠ only ${rep.found} firing(s) within the ${rep.horizonYears}-year horizon (requested ${rep.requested})`,
+    },
+};
+/** 人間向け表示（stdout 行列）。--json と同じ CliReport から出す */
+export function renderHuman(rep, lang = 'ja') {
+    const T = CLI_STRINGS[lang];
+    const out = [];
+    rep.results.forEach((res, i) => {
+        if (rep.results.length > 1)
+            out.push(T.exprHead(i + 1, res.dates.length));
+        for (const d of res.dates)
+            out.push(d);
+        // 区間註釈（ADR-37 判断 5/7 (a)）: 結果の後に表示——対処は呼び手の責務（判定は外部）
+        for (const a of res.annotations)
+            out.push(`# ⚠ ${formatAnnotation(a)}`);
+    });
+    // 被覆サマリ（ADR-37 判断 7 (b)）: クリップしない・完結主張も常時表示
+    if (rep.coverage.length > 0) {
+        out.push(T.coverageHead);
+        for (const c of rep.coverage) {
+            out.push(`#   ${c.source} covering ${c.covering}${c.asof ? ` asof ${c.asof}` : ''}`
+                + `${c.concluded ? T.concluded : ''}`
+                + ` ${T.runway(c.runwayDays)}`);
+        }
+    }
+    return out;
+}
+const USAGE_JA = `使い方（kairos ＝ node src/cli.ts）:
+  kairos list [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--tz Zone] [--supply data.json] [--json] [--lang en] <file.kairos>
+      範囲 [from, to) の全発火・区間註釈・被覆サマリ（既定: 実行 tz の今日から 1 年）
+  kairos next [-n 件数] [--from YYYY-MM-DD] [--horizon 年数] [--tz Zone] [--supply data.json] [--json] [--lang en] <file.kairos>
+      from 以降の次の N 発火（既定: n=1・from=今日・地平線 10 年。本体式 1 つのファイル向け）
+  --supply: external の解決値を静的束で渡す——{束縛名: {dates|instants, covering, asof [, labels]}}
+  --lang en: 定型出力の枠組みを英語表示（エラー・註釈文は日本語が正のまま・--json は言語中立）
+サブコマンド省略時は list・--version で実装版。終了コード: 0=成功・1=エラー・2=next が地平線内に要求件数未達`;
+const USAGE_EN = `Usage (kairos = node src/cli.ts):
+  kairos list [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--tz Zone] [--supply data.json] [--json] [--lang en] <file.kairos>
+      All firings in [from, to) plus interval annotations and the coverage summary
+      (default: one year from today in the execution tz)
+  kairos next [-n count] [--from YYYY-MM-DD] [--horizon years] [--tz Zone] [--supply data.json] [--json] [--lang en] <file.kairos>
+      The next N firings at or after from (default: n=1, from=today, horizon 10 years;
+      intended for files with a single body expression)
+  --supply: static bundle resolving external() — {binding: {dates|instants, covering, asof [, labels]}}
+  --lang en: English framing for the human-readable output. Evaluator messages (errors and
+      annotation texts) stay in Japanese — the implementation's canonical output language;
+      --json output is language-neutral.
+Without a subcommand, list is assumed. --version prints the implementation version.
+Exit codes: 0=success, 1=error, 2=next found fewer firings than requested within the horizon`;
+/** USAGE の言語選択——パース失敗経路でも使えるよう argv の素朴な走査で決める */
+const pickUsage = (argv) => argv.includes('--lang') && argv[argv.indexOf('--lang') + 1] === 'en' ? USAGE_EN : USAGE_JA;
+const OPTS = {
+    list: {
+        from: { type: 'string' }, to: { type: 'string' },
+        tz: { type: 'string' }, supply: { type: 'string' }, json: { type: 'boolean' },
+        lang: { type: 'string' },
+    },
+    next: {
+        n: { type: 'string', short: 'n' }, from: { type: 'string' }, horizon: { type: 'string' },
+        tz: { type: 'string' }, supply: { type: 'string' }, json: { type: 'boolean' },
+        lang: { type: 'string' },
+    },
+};
+const posInt = (s, name) => {
+    if (!/^\d+$/.test(s) || +s < 1)
+        throw new KairosError(`${name} は正の整数: ${s}`);
+    return +s;
+};
+/** 入口（SEA ビルドのエントリスタブからも呼ぶ）。戻り値＝終了コード */
+export function main(argv) {
+    if (argv[0] === '--version' || argv[0] === '-v') { // 配布バイナリの身元確認（単体で 0 終了）
+        console.log(VERSION);
+        return 0;
+    }
+    let cmd;
+    let rest = argv;
+    if (argv[0] === 'list' || argv[0] === 'next') {
+        cmd = argv[0];
+        rest = argv.slice(1);
+    }
+    else if (argv.length > 0 && !argv[0].startsWith('-')) {
+        cmd = 'list'; // 旧形式: kairos <file.kairos> --from … --to …
+    }
+    else {
+        console.error(pickUsage(argv));
+        return 1;
+    }
+    try {
+        const { values, positionals } = parseArgs({ args: rest, options: OPTS[cmd], allowPositionals: true, strict: true });
+        const langValue = values.lang ?? 'ja';
+        if (langValue !== 'ja' && langValue !== 'en') {
+            throw new KairosError(`--lang は ja または en: ${langValue}`);
+        }
+        const lang = langValue;
+        const T = CLI_STRINGS[lang];
+        if (positionals.length !== 1)
+            throw new KairosError('ファイルを 1 つ指定する');
+        const source = readFileSync(positionals[0], 'utf8');
+        const tz = values.tz;
+        const from = values.from ?? todayIn(tz ?? 'Asia/Tokyo');
+        const supplyPath = values.supply;
+        let resolve;
+        if (supplyPath) {
+            const text = readFileSync(supplyPath, 'utf8');
+            let json;
+            try {
+                json = JSON.parse(text);
+            }
+            catch (e) {
+                throw new KairosError(`--supply の JSON が壊れている（${supplyPath}）: ${e.message}`);
+            }
+            resolve = supplyResolver(json, supplyPath);
+        }
+        let rep;
+        if (cmd === 'list') {
+            const to = values.to ?? addYears(from, 1);
+            rep = cmdList(source, { from, to, ...(tz ? { tz } : {}), ...(resolve ? { resolve } : {}) });
+        }
+        else {
+            const n = posInt(values.n ?? '1', '-n');
+            const horizonYears = posInt(values.horizon ?? '10', '--horizon');
+            rep = cmdNext(source, { from, n, horizonYears, ...(tz ? { tz } : {}),
+                ...(resolve ? { resolve } : {}) });
+        }
+        if (values.json)
+            console.log(JSON.stringify(rep, null, 2));
+        else
+            for (const line of renderHuman(rep, lang))
+                console.log(line);
+        for (const w of rep.warnings)
+            console.error(T.warning(w));
+        if (rep.command === 'next' && rep.found < rep.requested) {
+            console.error(T.horizonShort(rep));
+            return 2;
+        }
+        return 0;
+    }
+    catch (e) {
+        console.error(String(e instanceof Error ? e.message : e));
+        if (e instanceof Error && 'code' in e && String(e.code).startsWith('ERR_PARSE_ARGS')) {
+            console.error(pickUsage(argv)); // 引数の誤り（未知フラグ等）には使い方を添える
+        }
+        return 1;
+    }
+}
+// vitest からの import では実行しない（テストは cmdList/cmdNext/renderHuman を直接呼ぶ）。
+// npm の bin は node_modules/.bin/kairos → dist/cli.js のシンボリックリンクで、argv[1] がリンク側・import.meta.url が
+// 実体側になる——URL の文字列一致では main() が走らず黙って終了した（2026-09-07 pack→install 実走で検出）。
+// realpath で比較する。SEA（tools/build-sea）は import.meta.url を undefined に潰すので偽に落ち、二重実行しない。
+const isMain = (() => {
+    if (!process.argv[1] || typeof import.meta.url !== 'string')
+        return false;
+    try {
+        return realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
+    }
+    catch {
+        return false;
+    }
+})();
+if (isMain)
+    process.exit(main(process.argv.slice(2)));