create-tx5dr-plugin 2.0.0 → 2.5.0

package/README.md

@@ -14,7 +14,7 @@ npx create-tx5dr-plugin [name] [options]
 |------|-------------|---------|
 | `--type <utility\|strategy>` | Plugin type | `utility` |
 | `--lang <ts\|js>` | Language | `ts` |
-| `--template <basic\|ui-vanilla\|ui-react\|ui-vue>` | Project template | `basic` |
+| `--template <basic\|ui-vanilla\|ui-react\|ui-vue\|ft8-contest>` | Project template | `basic` |
 | `--help, -h` | Show help | |
 
 ### Templates
@@ -25,6 +25,12 @@ npx create-tx5dr-plugin [name] [options]
 | `ui-vanilla` | Plugin with vanilla HTML/JS/CSS UI page |
 | `ui-react` | Plugin with React + Vite UI page |
 | `ui-vue` | Plugin with Vue + Vite UI page |
+| `ft8-contest` | TypeScript strategy with composable FT8/FT4 contest rules and tests |
+
+`ft8-contest` fixes the type to `strategy` and language to `ts`; conflicting
+explicit `--type` or `--lang` values are rejected. Its build emits declarations
+with TypeScript and a self-contained ESM `dist/index.mjs` with esbuild, so the
+Host can load the linked plugin directory without the project `node_modules`.
 
 ### Examples
 
@@ -46,6 +52,9 @@ npx create-tx5dr-plugin my-plugin --template ui-vue
 
 # Vanilla UI (no build step for UI files)
 npx create-tx5dr-plugin my-plugin --template ui-vanilla
+
+# FT8 contest strategy with rule modules and test kit
+npx create-tx5dr-plugin my-contest --template ft8-contest
 ```
 
 ## Generated Structure

package/dist/index.d.ts

@@ -7,5 +7,6 @@
  *   npx create-tx5dr-plugin my-plugin                    # Name only, prompts for rest
  *   npx create-tx5dr-plugin my-plugin --type utility     # Non-interactive
  *   npx create-tx5dr-plugin my-plugin --template ui-react
+ *   npx create-tx5dr-plugin my-contest --template ft8-contest
  */
 export {};

package/dist/index.js

@@ -7,11 +7,14 @@
  *   npx create-tx5dr-plugin my-plugin                    # Name only, prompts for rest
  *   npx create-tx5dr-plugin my-plugin --type utility     # Non-interactive
  *   npx create-tx5dr-plugin my-plugin --template ui-react
+ *   npx create-tx5dr-plugin my-contest --template ft8-contest
  */
-import { mkdirSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
 import { join, resolve } from 'node:path';
 import { createInterface } from 'node:readline';
-const VALID_TEMPLATES = ['basic', 'ui-vanilla', 'ui-react', 'ui-vue'];
+const require = createRequire(import.meta.url);
+const VALID_TEMPLATES = ['basic', 'ui-vanilla', 'ui-react', 'ui-vue', 'ft8-contest'];
 // ===== CLI argument parsing =====
 function parseArgs() {
     const args = process.argv.slice(2);
@@ -58,7 +61,7 @@ function printUsage() {
   Options:
     --type <utility|strategy>                        Plugin type (default: utility)
     --lang <ts|js>                                   Language (default: ts)
-    --template <basic|ui-vanilla|ui-react|ui-vue>    Template (default: basic)
+    --template <basic|ui-vanilla|ui-react|ui-vue|ft8-contest>  Template (default: basic)
     --help, -h                                       Show this help message
 
   Templates:
@@ -66,12 +69,14 @@ function printUsage() {
     ui-vanilla   Plugin with vanilla HTML/JS/CSS UI page
     ui-react     Plugin with React + Vite UI page
     ui-vue       Plugin with Vue + Vite UI page
+    ft8-contest  TypeScript strategy with composable FT8 contest rules
 
   Examples:
     npx create-tx5dr-plugin my-plugin
     npx create-tx5dr-plugin my-plugin --type strategy
     npx create-tx5dr-plugin my-plugin --template ui-react
     npx create-tx5dr-plugin my-plugin --template ui-vue --type utility
+    npx create-tx5dr-plugin my-contest --template ft8-contest
   `);
 }
 // ===== Interactive prompts =====
@@ -88,21 +93,29 @@ async function promptConfig(partial) {
             console.error('Plugin name is required.');
             process.exit(1);
         }
-        let type = partial.type;
-        if (!type) {
+        let template = partial.template;
+        if (!template) {
+            const answer = await prompt(rl, 'Template (basic/ui-vanilla/ui-react/ui-vue/ft8-contest) [basic]: ');
+            template = VALID_TEMPLATES.includes(answer) ? answer : 'basic';
+        }
+        if (template === 'ft8-contest' && partial.type && partial.type !== 'strategy') {
+            console.error('The ft8-contest template requires --type strategy.');
+            process.exit(1);
+        }
+        if (template === 'ft8-contest' && partial.lang && partial.lang !== 'ts') {
+            console.error('The ft8-contest template requires --lang ts.');
+            process.exit(1);
+        }
+        let type = template === 'ft8-contest' ? 'strategy' : partial.type ?? 'utility';
+        if (!partial.type && template !== 'ft8-contest') {
             const answer = await prompt(rl, 'Plugin type (utility/strategy) [utility]: ');
             type = answer === 'strategy' ? 'strategy' : 'utility';
         }
-        let lang = partial.lang;
-        if (!lang) {
+        let lang = template === 'ft8-contest' ? 'ts' : partial.lang ?? 'ts';
+        if (!partial.lang && template !== 'ft8-contest') {
             const answer = await prompt(rl, 'Language (ts/js) [ts]: ');
             lang = answer === 'js' ? 'js' : 'ts';
         }
-        let template = partial.template;
-        if (!template) {
-            const answer = await prompt(rl, 'Template (basic/ui-vanilla/ui-react/ui-vue) [basic]: ');
-            template = VALID_TEMPLATES.includes(answer) ? answer : 'basic';
-        }
         return { name, type, lang, template };
     }
     finally {
@@ -111,19 +124,42 @@ async function promptConfig(partial) {
 }
 // ===== Helpers =====
 function hasUI(config) {
-    return config.template !== 'basic';
+    return config.template === 'ui-vanilla'
+        || config.template === 'ui-react'
+        || config.template === 'ui-vue';
 }
 function hasVite(config) {
     return config.template === 'ui-react' || config.template === 'ui-vue';
 }
+function readContestLogbookUiAssets() {
+    const entry = require.resolve('@tx5dr/plugin-api/contest-logbook-ui/contest-log.html');
+    const root = resolve(entry, '..');
+    const files = new Map();
+    const visit = (directory, prefix) => {
+        for (const name of readdirSync(directory)) {
+            const source = join(directory, name);
+            const relative = join(prefix, name);
+            if (statSync(source).isDirectory())
+                visit(source, relative);
+            else
+                files.set(`ui/${relative}`, readFileSync(source, 'utf8'));
+        }
+    };
+    if (!existsSync(root))
+        throw new Error('contest-logbook-ui-assets-missing');
+    visit(root, '');
+    return files;
+}
 // ===== Core template generation =====
 function generatePackageJson(config) {
     const devDeps = {
-        '@tx5dr/plugin-api': 'latest',
+        '@tx5dr/plugin-api': '^2.5.0',
     };
     if (config.lang === 'ts') {
         devDeps['typescript'] = '^5.0.0';
         devDeps['vitest'] = '^1.0.0';
+        if (config.template === 'ft8-contest')
+            devDeps['esbuild'] = '^0.25.0';
     }
     if (hasVite(config)) {
         devDeps['vite'] = '^6.0.0';
@@ -141,7 +177,14 @@ function generatePackageJson(config) {
     }
     const scripts = {};
     if (config.lang === 'ts') {
-        if (hasVite(config)) {
+        if (config.template === 'ft8-contest') {
+            scripts['build'] = 'npm run build:types && npm run build:bundle';
+            scripts['build:types'] = 'tsc --emitDeclarationOnly';
+            scripts['build:bundle'] = 'esbuild src/index.ts --bundle --platform=node --format=esm --target=node20 --legal-comments=none --outfile=dist/index.mjs';
+            scripts['typecheck'] = 'tsc --noEmit';
+            scripts['dev'] = 'esbuild src/index.ts --bundle --platform=node --format=esm --target=node20 --legal-comments=none --outfile=dist/index.mjs --watch';
+        }
+        else if (hasVite(config)) {
             scripts['build'] = 'tsc && npm run build:ui';
             scripts['build:ui'] = 'vite build --config ui/vite.config.ts';
             scripts['dev:server'] = 'tsc --watch';
@@ -159,11 +202,33 @@ function generatePackageJson(config) {
         version: '0.1.0',
         type: 'module',
         ...(config.lang === 'ts'
-            ? { main: 'dist/index.js', types: 'dist/index.d.ts' }
+            ? {
+                main: config.template === 'ft8-contest' ? 'dist/index.mjs' : 'dist/index.js',
+                types: 'dist/index.d.ts',
+            }
             : { main: 'index.js' }),
         scripts,
         devDependencies: devDeps,
     };
+    if (config.template === 'ft8-contest') {
+        pkg.tx5drPlugin = {
+            pluginName: config.name,
+            title: config.name,
+            description: `${config.name} FT8/FT4 contest strategy`,
+            minPluginApiVersion: '2.5.0',
+            author: 'TX-5DR plugin author',
+            license: 'GPL-3.0-only',
+            categories: ['contest', 'ft8', 'ft4'],
+            keywords: ['amateur-radio', 'contest', config.name],
+            entry: 'dist/index.mjs',
+            include: [
+                { from: 'dist/index.mjs', to: 'index.mjs' },
+                { from: 'ui', to: 'ui' },
+                { from: 'src/locales', to: 'locales' },
+                { from: 'README.md', to: 'README.md' },
+            ],
+        };
+    }
     return JSON.stringify(pkg, null, 2) + '\n';
 }
 function generateTsConfig() {
@@ -191,6 +256,9 @@ dist/
 function generateLocaleZh(config) {
     return JSON.stringify({
         pluginDescription: `${config.name} plugin`,
+        contestLogTitle: '比赛日志',
+        contestNewCallsign: '本波段新台',
+        contestNewMultiplier: '新系数',
         enabled: '启用自动发射控制',
         enabledDesc: '允许此插件通过宿主发射协调器影响当前操作员的自动通联',
     }, null, 2) + '\n';
@@ -198,6 +266,9 @@ function generateLocaleZh(config) {
 function generateLocaleEn(config) {
     return JSON.stringify({
         pluginDescription: `${config.name} plugin`,
+        contestLogTitle: 'Contest log',
+        contestNewCallsign: 'New on band',
+        contestNewMultiplier: 'New multiplier',
         enabled: 'Enable automatic transmit control',
         enabledDesc: 'Allow this plugin to influence operator automation through the host coordinator',
     }, null, 2) + '\n';
@@ -371,6 +442,156 @@ export const locales: Record<string, Record<string, string>> = {
   en: enLocale,
 };
 
+export default plugin;
+`;
+}
+function generateTsFT8ContestPlugin(config) {
+    return `import {
+  type FrameMessage,
+  type ParsedFT8Message,
+  type SlotInfo,
+  type StrategyDecisionMetaV2,
+  type StrategyDecisionResult,
+  type StrategyPluginContext,
+  type StrategyRuntime,
+  type StrategyRuntimeCheckpoint,
+  type StrategyRuntimeContext,
+  type StrategyRuntimeSlot,
+  type StrategyRuntimeSlotContentUpdate,
+  type StrategyRuntimeSnapshot,
+} from '@tx5dr/plugin-api';
+import {
+  cabrilloSubmission,
+  CONTEST_LOGBOOK_PERMISSIONS,
+  composeFT8ContestPlugin,
+  createContestQsoEnvelopeAdapter,
+  defineFT8Contest,
+  distancePoints,
+  fixedWeekendEdition,
+  gridExchange,
+  requireExchangeAndFinalAck,
+  type FT8ContestQso,
+  standardFT8ContestLogbook,
+  type GridExchange,
+} from '@tx5dr/plugin-api/contest';
+import zhLocale from './locales/zh.json' with { type: 'json' };
+import enLocale from './locales/en.json' with { type: 'json' };
+import jaLocale from './locales/ja.json' with { type: 'json' };
+
+export type ContestQso = FT8ContestQso<GridExchange> & {
+  frequencyKhz: number;
+  cabrilloDateTime: string;
+};
+
+export const contest = defineFT8Contest<GridExchange, ContestQso>({
+  id: '${config.name}',
+  rulesetVersion: '2026.1',
+  edition: fixedWeekendEdition({
+    id: '2026',
+    // Replace these example boundaries and record the official rule source.
+    startAt: '2026-01-03T00:00:00Z',
+    endAt: '2026-01-04T00:00:00Z',
+  }),
+  bands: ['80M', '40M', '20M', '15M', '10M'],
+  exchange: gridExchange(),
+  // Completion is explicit because it belongs to the RF fail-closed boundary.
+  completion: requireExchangeAndFinalAck(),
+  scoring: distancePoints<ContestQso>({ stepKm: 3000 }),
+  submission: cabrilloSubmission<ContestQso>({
+    headers: () => [['CONTEST', '${config.name.toUpperCase()}']],
+    qsoLine: (qso) =>
+      \`QSO: \${qso.frequencyKhz} DG \${qso.cabrilloDateTime} \${qso.callsign}\`,
+  }),
+});
+
+export const contestEnvelope = createContestQsoEnvelopeAdapter(contest);
+
+export const logbook = standardFT8ContestLogbook({ contest });
+
+class ContestRuntime implements StrategyRuntime {
+  private state: StrategyRuntimeSlot = 'TX6';
+  private slots: Partial<Record<StrategyRuntimeSlot, string>> = {};
+  private context: StrategyRuntimeContext = {};
+
+  constructor(private readonly ctx: StrategyPluginContext) {}
+
+  checkpoint(): StrategyRuntimeCheckpoint {
+    return structuredClone({ state: this.state, slots: this.slots, context: this.context });
+  }
+
+  restore(checkpoint: StrategyRuntimeCheckpoint): void {
+    const saved = checkpoint as {
+      state: StrategyRuntimeSlot;
+      slots: Partial<Record<StrategyRuntimeSlot, string>>;
+      context: StrategyRuntimeContext;
+    };
+    this.state = saved.state;
+    this.slots = { ...saved.slots };
+    this.context = { ...saved.context };
+  }
+
+  decide(messages: ParsedFT8Message[], meta: StrategyDecisionMetaV2): StrategyDecisionResult {
+    if (meta.signal.aborted) throw meta.signal.reason ?? new Error('Strategy decision aborted');
+    // Apply the contest exchange/completion modules in your protocol reducer here.
+    return { transmission: this.getTransmitText(), snapshot: this.getSnapshot() };
+  }
+
+  getTransmitText(): string | null {
+    return this.slots[this.state] ?? null;
+  }
+
+  requestCall(callsign: string, lastMessage?: { message: FrameMessage; slotInfo: SlotInfo }): void {
+    this.context.targetCallsign = callsign;
+    this.state = 'TX1';
+    this.ctx.log.info('Contest call requested', { callsign });
+  }
+
+  getSnapshot(): StrategyRuntimeSnapshot {
+    return {
+      currentState: this.state,
+      slots: { ...this.slots },
+      context: { ...this.context },
+      availableSlots: ['TX1', 'TX2', 'TX3', 'TX4', 'TX5', 'TX6'],
+    };
+  }
+
+  patchContext(patch: Partial<StrategyRuntimeContext>): void {
+    Object.assign(this.context, patch);
+  }
+
+  setState(state: StrategyRuntimeSlot): void {
+    this.state = state;
+  }
+
+  setSlotContent(update: StrategyRuntimeSlotContentUpdate): void {
+    this.slots[update.slot] = update.content;
+  }
+
+  reset(reason?: string): void {
+    this.state = 'TX6';
+    this.slots = {};
+    this.context = {};
+    this.ctx.log.info('Contest strategy reset', { reason });
+  }
+}
+
+export const plugin = composeFT8ContestPlugin({
+  name: '${config.name}',
+  version: '0.1.0',
+  minPluginApiVersion: '2.5.0',
+  description: 'pluginDescription',
+  permissions: CONTEST_LOGBOOK_PERMISSIONS,
+  contest,
+  logbook,
+  runtime: (_contest, context) => new ContestRuntime(context),
+});
+
+export const locales: Record<string, Record<string, string>> = {
+  zh: zhLocale,
+  en: enLocale,
+  ja: jaLocale,
+};
+
 export default plugin;
 `;
 }
@@ -542,6 +763,48 @@ export default plugin;
 }
 // ===== Test templates =====
 function generateTsTest(config) {
+    if (config.template === 'ft8-contest') {
+        return `import { describe, it, expect } from 'vitest';
+import { createFT8ContestTestKit } from '@tx5dr/plugin-api/contest';
+import { contest, contestEnvelope, plugin } from '../index.js';
+
+describe('${config.name}', () => {
+  const kit = createFT8ContestTestKit(contest);
+
+  it('exposes an FT8 strategy plugin', () => {
+    expect(plugin.type).toBe('strategy');
+      expect(plugin.minPluginApiVersion).toBe('2.5.0');
+    expect(contest.operating).toMatchObject({
+      humanInitiation: 'required',
+      maxConcurrentQsos: 1,
+      maxSimultaneousSignals: 1,
+    });
+  });
+
+  it('round-trips the contest exchange', () => {
+    kit.exchange({ grid: 'FN31' }, { grid: 'FN31' });
+    kit.invalidExchange({ grid: 'ZZ99' }, 'invalid_grid');
+  });
+
+  it('requires exchange and a final acknowledgement', () => {
+    kit.completion({
+      sentExchange: { grid: 'PL04' },
+      receivedExchange: { grid: 'FN31' },
+      receivedFinalAck: true,
+    }, true);
+  });
+
+  it('creates an identity-bound contest QSO envelope', () => {
+    const envelope = contestEnvelope.create({
+      sent: { grid: 'PL04' },
+      received: { grid: 'FN31' },
+    });
+    expect(contestEnvelope.validate(envelope).ok).toBe(true);
+    expect(envelope.rulesetVersion).toBe(contest.rulesetVersion);
+  });
+});
+`;
+    }
     if (config.type === 'strategy') {
         return `import { describe, it, expect } from 'vitest';
 import { createMockContext, createMockSlotInfo, createMockParsedMessage } from '@tx5dr/plugin-api/testing';
@@ -1106,7 +1369,13 @@ function generateFiles(config) {
     files.set('.gitignore', generateGitignore());
     if (config.lang === 'ts') {
         files.set('tsconfig.json', generateTsConfig());
-        if (config.type === 'strategy') {
+        if (config.template === 'ft8-contest') {
+            files.set('src/index.ts', generateTsFT8ContestPlugin(config));
+            for (const [relativePath, content] of readContestLogbookUiAssets())
+                files.set(relativePath, content);
+            files.set('README.md', `# ${config.name}\n\nFT8/FT4 contest strategy plugin for TX-5DR.\n`);
+        }
+        else if (config.type === 'strategy') {
             files.set('src/index.ts', generateTsStrategyPlugin(config));
         }
         else if (hasUI(config)) {
@@ -1117,6 +1386,8 @@ function generateFiles(config) {
         }
         files.set('src/locales/zh.json', generateLocaleZh(config));
         files.set('src/locales/en.json', generateLocaleEn(config));
+        if (config.template === 'ft8-contest')
+            files.set('src/locales/ja.json', JSON.stringify({ pluginDescription: `${config.name} plugin`, contestLogTitle: 'コンテストログ', contestNewCallsign: 'このバンドで未交信', contestNewMultiplier: '新マルチ' }, null, 2) + '\n');
         files.set('src/__tests__/plugin.test.ts', generateTsTest(config));
     }
     else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-tx5dr-plugin",
-  "version": "2.0.0",
+  "version": "2.5.0",
   "type": "module",
   "description": "Scaffold a new TX-5DR plugin project",
   "license": "MIT",
@@ -22,7 +22,11 @@
   ],
   "scripts": {
     "build": "tsc",
-    "dev": "tsc --watch"
+    "dev": "tsc --watch",
+    "smoke:ft8-contest": "node scripts/ft8-contest-smoke.mjs"
+  },
+  "dependencies": {
+    "@tx5dr/plugin-api": "^2.5.0"
   },
   "devDependencies": {
     "typescript": "^5.0.0"