@cadence-app/compiler 0.3.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -34,8 +34,8 @@ squelettes, par `--template` : `page` (défaut), `onglets` pour une tab bar, `co
34
34
  composant à soi. Il pose aussi un `package.json` et un `tsconfig.json`, sans lesquels un éditeur
35
35
  souligne en rouge des imports que le build résout très bien — reste à lancer `npm install`.
36
36
 
37
- `build` rend un dossier `dist` : `engine.js`, `app.js`, la feuille de thème, les pages, les icônes
38
- et une archive prête à distribuer. Le budget du moteur — 30 ko gzip — est vérifié à chaque
37
+ `build` rend un dossier `dist` : `engine.js`, `app.js`, la feuille de thème, les pages, les icônes,
38
+ le dossier `assets/` copié tel quel et une archive prête à distribuer. Le budget du moteur — 30 ko gzip — est vérifié à chaque
39
39
  construction, et un dépassement fait échouer la commande.
40
40
 
41
41
  `dev` sert le mini-programme dans un navigateur, avec un hôte simulé : le geste retour tient à la
@@ -0,0 +1,19 @@
1
+ export interface CopiedAsset {
2
+ /** Chemin dans le bundle, tel qu'une feuille de style doit l'écrire. */
3
+ readonly path: string;
4
+ readonly bytes: number;
5
+ }
6
+ /**
7
+ * Copie `assets/` du mini-programme dans le bundle, à l'identique.
8
+ *
9
+ * Polices, images et sons n'ont jamais eu de chemin : le conteneur sait pourtant
10
+ * servir n'importe quel fichier du bundle, types MIME compris, et seul le build
11
+ * manquait. Un mini-programme qui veut sa propre voix typographique n'a donc
12
+ * aujourd'hui que la police du système.
13
+ *
14
+ * Les noms sont gardés tels quels plutôt qu'empreintés : la feuille de style du
15
+ * mini-programme les écrit à la main, et les réécrire demanderait de relire le
16
+ * CSS compilé. Le cache se règle ailleurs — un bundle est versionné entier et
17
+ * installé d'un bloc.
18
+ */
19
+ export declare function copyAppAssets(miniappDir: string, outDir: string): Promise<readonly CopiedAsset[]>;
@@ -0,0 +1,41 @@
1
+ import { existsSync } from 'node:fs';
2
+ import { copyFile, mkdir, readdir, stat } from 'node:fs/promises';
3
+ import path from 'node:path';
4
+ const ASSETS_DIRECTORY = 'assets';
5
+ /**
6
+ * Copie `assets/` du mini-programme dans le bundle, à l'identique.
7
+ *
8
+ * Polices, images et sons n'ont jamais eu de chemin : le conteneur sait pourtant
9
+ * servir n'importe quel fichier du bundle, types MIME compris, et seul le build
10
+ * manquait. Un mini-programme qui veut sa propre voix typographique n'a donc
11
+ * aujourd'hui que la police du système.
12
+ *
13
+ * Les noms sont gardés tels quels plutôt qu'empreintés : la feuille de style du
14
+ * mini-programme les écrit à la main, et les réécrire demanderait de relire le
15
+ * CSS compilé. Le cache se règle ailleurs — un bundle est versionné entier et
16
+ * installé d'un bloc.
17
+ */
18
+ export async function copyAppAssets(miniappDir, outDir) {
19
+ const sourceDir = path.join(miniappDir, ASSETS_DIRECTORY);
20
+ if (!existsSync(sourceDir)) {
21
+ return [];
22
+ }
23
+ const copied = await copyTree(sourceDir, path.join(outDir, ASSETS_DIRECTORY), ASSETS_DIRECTORY);
24
+ return [...copied].sort((left, right) => left.path.localeCompare(right.path));
25
+ }
26
+ async function copyTree(sourceDir, targetDir, bundlePrefix) {
27
+ await mkdir(targetDir, { recursive: true });
28
+ const entries = await readdir(sourceDir, { withFileTypes: true });
29
+ const copied = [];
30
+ for (const entry of entries) {
31
+ const source = path.join(sourceDir, entry.name);
32
+ const bundlePath = `${bundlePrefix}/${entry.name}`;
33
+ if (entry.isDirectory()) {
34
+ copied.push(...(await copyTree(source, path.join(targetDir, entry.name), bundlePath)));
35
+ continue;
36
+ }
37
+ await copyFile(source, path.join(targetDir, entry.name));
38
+ copied.push({ path: bundlePath, bytes: (await stat(source)).size });
39
+ }
40
+ return copied;
41
+ }
package/dist/build.d.ts CHANGED
@@ -1,3 +1,4 @@
1
+ import { type CopiedAsset } from './app-assets.js';
1
2
  import type { MiniAppManifest } from './manifest.js';
2
3
  export declare class BuildError extends Error {
3
4
  constructor(message: string);
@@ -21,6 +22,7 @@ export interface BuildSummary {
21
22
  readonly minified: boolean;
22
23
  readonly engine: SizeReport;
23
24
  readonly app: SizeReport;
25
+ readonly assets: readonly CopiedAsset[];
24
26
  readonly zipFile: string | null;
25
27
  }
26
28
  /**
package/dist/build.js CHANGED
@@ -6,6 +6,8 @@ import { fileURLToPath } from 'node:url';
6
6
  import { gzipSync } from 'node:zlib';
7
7
  import * as esbuild from 'esbuild';
8
8
  import JSZip from 'jszip';
9
+ import { copyAppAssets } from "./app-assets.js";
10
+ import { DEV_CLIENT_ENTRY, DEV_HOST_ENTRY, DEV_SCAFFOLD_FILES, DEV_SHELL_FILE, ENTRY_DOCUMENT, } from "./dev-scaffold.js";
9
11
  import { generateRenderFunction } from "./template/codegen.js";
10
12
  import { parseTemplate } from "./template/parser.js";
11
13
  import { compileStyle } from "./style/compile-style.js";
@@ -23,19 +25,6 @@ const HOST_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), 'host')
23
25
  change donc d'extension selon l'endroit d'où le compilateur tourne. */
24
26
  const HOST_EXTENSION = existsSync(path.join(HOST_DIR, 'engine-entry.ts')) ? '.ts' : '.js';
25
27
  const ENGINE_TARGET = 'es2020';
26
- const DEV_SHELL_FILE = 'dev.html';
27
- const DEV_HOST_ENTRY = 'dev-host';
28
- const DEV_CLIENT_ENTRY = 'dev-client';
29
- /**
30
- * L'échafaudage que `mini dev` sert dans le navigateur. Il reste dans `outDir`,
31
- * mais l'archive part sur le serveur de distribution et jusque sur les
32
- * appareils : elle n'embarque que ce que le conteneur exécute.
33
- */
34
- const DEV_SCAFFOLD_FILES = new Set([
35
- DEV_SHELL_FILE,
36
- `${DEV_HOST_ENTRY}.js`,
37
- `${DEV_CLIENT_ENTRY}.js`,
38
- ]);
39
28
  /**
40
29
  * Pipeline complet : manifest → compilation template+SCSS de chaque unité →
41
30
  * bundle esbuild (app + sous-packages, imports `@cadence/*` shimés vers le
@@ -66,10 +55,11 @@ export async function buildMiniApp(options) {
66
55
  });
67
56
  await rm(outDir, { recursive: true, force: true });
68
57
  await mkdir(outDir, { recursive: true });
69
- await bundleApp(outDir, virtualModules, subEntryNames, minified);
58
+ await bundleApp(miniappDir, outDir, virtualModules, subEntryNames, minified);
70
59
  await bundleHostScripts(outDir, minified);
71
60
  await writeHtmlShells(outDir, manifest.language ?? DEFAULT_DOCUMENT_LANGUAGE);
72
61
  await writeFile(path.join(outDir, 'manifest.json'), JSON.stringify(manifest, null, 2));
62
+ const assets = await copyAppAssets(miniappDir, outDir);
73
63
  const engine = await measure(path.join(outDir, 'engine.js'));
74
64
  const app = await measure(path.join(outDir, 'app.js'));
75
65
  const zipFile = (options.zip ?? true) ? await writeBundleArchive(outDir, manifest) : null;
@@ -82,6 +72,7 @@ export async function buildMiniApp(options) {
82
72
  minified,
83
73
  engine,
84
74
  app,
75
+ assets,
85
76
  zipFile,
86
77
  };
87
78
  }
@@ -246,7 +237,7 @@ function generateSubPackageEntry(pages) {
246
237
  });
247
238
  return lines.join('\n');
248
239
  }
249
- async function bundleApp(outDir, virtualModules, subEntryNames, minify) {
240
+ async function bundleApp(miniappDir, outDir, virtualModules, subEntryNames, minify) {
250
241
  const entryPoints = { app: 'cadence-entry:main' };
251
242
  for (const name of subEntryNames) {
252
243
  entryPoints[`subpackages/${name}`] = `cadence-entry:${name}`;
@@ -257,6 +248,7 @@ async function bundleApp(outDir, virtualModules, subEntryNames, minify) {
257
248
  entryNames: '[dir]/[name]',
258
249
  minify,
259
250
  plugins: [virtualModulesPlugin(virtualModules), cadenceShimPlugin()],
251
+ moduleNamingRoot: miniappDir,
260
252
  });
261
253
  }
262
254
  async function bundleHostScripts(outDir, minify) {
@@ -270,6 +262,7 @@ async function bundleHostScripts(outDir, minify) {
270
262
  entryNames: '[name]',
271
263
  minify,
272
264
  plugins: [],
265
+ moduleNamingRoot: HOST_DIR,
273
266
  });
274
267
  }
275
268
  async function runEsbuild(run) {
@@ -284,6 +277,7 @@ async function runEsbuild(run) {
284
277
  target: ENGINE_TARGET,
285
278
  minify: run.minify,
286
279
  plugins: run.plugins,
280
+ absWorkingDir: run.moduleNamingRoot,
287
281
  logLevel: 'silent',
288
282
  });
289
283
  }
@@ -377,7 +371,7 @@ function cadenceShimPlugin() {
377
371
  };
378
372
  }
379
373
  async function writeHtmlShells(outDir, language) {
380
- await writeFile(path.join(outDir, 'index.html'), htmlShell(['engine.js', 'app.js'], language));
374
+ await writeFile(path.join(outDir, ENTRY_DOCUMENT), htmlShell(['engine.js', 'app.js'], language));
381
375
  await writeFile(path.join(outDir, DEV_SHELL_FILE), htmlShell(['engine.js', `${DEV_HOST_ENTRY}.js`, 'app.js', `${DEV_CLIENT_ENTRY}.js`], language));
382
376
  }
383
377
  /* Le `lang` du document décrit ce qu'on lit, pas qui lit : il vient donc du
@@ -405,9 +399,30 @@ async function measure(filePath) {
405
399
  const contents = await readFile(filePath);
406
400
  return { raw: contents.byteLength, gzip: gzipSync(contents).byteLength };
407
401
  }
402
+ const ARCHIVE_ENTRY_DATE = new Date(Date.UTC(1980, 0, 1));
403
+ /**
404
+ * Horodate toute entrée de l'archive à une date fixe, dossiers compris.
405
+ *
406
+ * L'empreinte de l'archive est son identité dans le canal de distribution.
407
+ * Deux compilations des mêmes sources doivent donc rendre les mêmes octets,
408
+ * sans quoi rien ne rattache un bundle publié à ses sources. JSZip, lui, date
409
+ * chaque entrée de `new Date()`.
410
+ *
411
+ * Le parcours vient après l'ajout des fichiers parce que JSZip crée les
412
+ * entrées de dossier de lui-même : une date passée à `zip.file` les laisserait
413
+ * dehors. Le plancher de l'époque DOS est l'usage des archives reproductibles,
414
+ * et JSZip l'écrit par des accesseurs UTC — le fuseau de la machine n'y entre
415
+ * pas.
416
+ */
417
+ function dateEveryEntry(zip) {
418
+ zip.forEach((_entryPath, entry) => {
419
+ entry.date = ARCHIVE_ENTRY_DATE;
420
+ });
421
+ }
408
422
  async function writeBundleArchive(outDir, manifest) {
409
423
  const zip = new JSZip();
410
424
  await addDirectoryToZip(zip, outDir, '', DEV_SCAFFOLD_FILES);
425
+ dateEveryEntry(zip);
411
426
  const archiveName = `${manifest.name}-${manifest.version}.zip`;
412
427
  const buffer = await zip.generateAsync({ type: 'nodebuffer', compression: 'DEFLATE' });
413
428
  await writeFile(path.join(outDir, archiveName), buffer);
package/dist/cli.js CHANGED
@@ -3,8 +3,13 @@ import path from 'node:path';
3
3
  import { parseArgs } from 'node:util';
4
4
  import { buildMiniApp } from "./build.js";
5
5
  import { startDevServer } from "./dev-server.js";
6
+ import { ENTRY_DOCUMENT } from "./dev-scaffold.js";
7
+ import { channelDeepLink, pairingDeepLink } from "./dev-deep-link.js";
6
8
  import { ENGINE_GZIP_BUDGET_BYTES, engineBudgetVerdict } from "./engine-budget.js";
7
9
  import { initProject } from "./init-project.js";
10
+ import { openDevChannel } from "./dev-channel-session.js";
11
+ import { encodeQrCode } from "./qr/qr-code.js";
12
+ import { renderQrForTerminal } from "./qr/terminal-render.js";
8
13
  import { PROJECT_TEMPLATES, PROJECT_TEMPLATE_NAMES } from "./project-templates.js";
9
14
  import { clearCredentials, credentialsPath, normalizeRemoteUrl, readCredentials, writeCredentials, } from "./publish/credentials.js";
10
15
  import { DistributionClient } from "./publish/distribution-client.js";
@@ -20,7 +25,9 @@ ${TEMPLATE_LINES}
20
25
 
21
26
  Compiler :
22
27
  mini build <dossier-miniapp> [--out <dossier>] [--minify] [--no-zip]
23
- mini dev <dossier-miniapp> [--out <dossier>] [--port <n>]
28
+ mini dev <dossier-miniapp> [--out <dossier>] [--port <n>] [--channel]
29
+ --channel ouvre aussi un canal de développement sur le serveur de
30
+ distribution : l'appareil n'a plus à partager le réseau
24
31
 
25
32
  Publier :
26
33
  mini login --remote <url> [--token <pat>]
@@ -28,6 +35,102 @@ Publier :
28
35
  mini whoami
29
36
  mini publish <dossier-miniapp> [--app-id <uuid>]
30
37
  `;
38
+ /**
39
+ * Les adresses de `mini dev` : le navigateur pour écrire, le conteneur pour
40
+ * vérifier sur un vrai appareil. Les deux se rechargent à chaque compilation.
41
+ */
42
+ function printDevAddresses(server, port) {
43
+ console.log(`mini dev — ${server.url}`);
44
+ console.log('');
45
+ console.log(' navigateur mock natif intégré (Échap = retour)');
46
+ console.log(` conteneur ${server.url}${ENTRY_DOCUMENT} — rechargé à chaque compilation`);
47
+ console.log('');
48
+ console.log('Sur un appareil :');
49
+ console.log(` USB adb reverse tcp:${port} tcp:${port}, puis la même adresse`);
50
+ for (const url of server.networkUrls) {
51
+ console.log(` Wi-Fi ${url}${ENTRY_DOCUMENT}`);
52
+ }
53
+ const [firstNetworkUrl] = server.networkUrls;
54
+ if (firstNetworkUrl === undefined) {
55
+ return;
56
+ }
57
+ console.log(" (Android n'autorise le clair que sur localhost : préférer l'USB)");
58
+ printPairingCode(firstNetworkUrl);
59
+ }
60
+ /**
61
+ * Le lien d'appariement, à lire avec l'appareil photo du téléphone.
62
+ *
63
+ * Aucun lecteur à écrire : le système reconnaît une adresse, et l'hôte l'a
64
+ * enregistrée. Le QR porte la première adresse annoncée — les autres restent
65
+ * au-dessus, à recopier si c'est celle-là qui ne répond pas.
66
+ */
67
+ function printPairingCode(networkUrl) {
68
+ const link = pairingDeepLink(networkUrl.replace(/\/$/, ''));
69
+ console.log('');
70
+ console.log("Ou le scanner avec l'appareil photo du téléphone :");
71
+ console.log('');
72
+ console.log(renderQrForTerminal(encodeQrCode(link)));
73
+ console.log('');
74
+ console.log(` ${link}`);
75
+ console.log('');
76
+ console.log("Le jeton de l'adresse Wi-Fi meurt avec ce serveur. Sans lui, un appareil");
77
+ console.log("du même réseau n'obtient rien.");
78
+ }
79
+ /**
80
+ * Ouvre le canal pour ce bundle : l'application nommée, ou le slug du manifeste.
81
+ */
82
+ function openChannelFor(summary, distDir, appId) {
83
+ return openDevChannel({
84
+ distDir,
85
+ slug: summary.manifest.name,
86
+ ...(appId === undefined ? {} : { appId }),
87
+ });
88
+ }
89
+ /**
90
+ * Les deux voies d'un canal (ADR-038) : le code, qui dispense d'un appareil
91
+ * photo et sert donc un émulateur, et le QR, qui épargne de le recopier.
92
+ */
93
+ function printChannelPairing(channel) {
94
+ const link = channelDeepLink(channel.pollUrl);
95
+ console.log('');
96
+ console.log('Par le canal de développement — ni câble, ni réseau partagé :');
97
+ console.log(` code ${channel.displayCode}`);
98
+ console.log(` interrogé ${channel.pollUrl}`);
99
+ if (channel.expiresAt !== null) {
100
+ console.log(` expire ${channel.expiresAt}`);
101
+ }
102
+ console.log('');
103
+ console.log(renderQrForTerminal(encodeQrCode(link)));
104
+ console.log('');
105
+ console.log(` ${link}`);
106
+ console.log('');
107
+ console.log("Rien de ce que porte ce canal ne s'installe sur l'appareil, et le code");
108
+ console.log('meurt avec lui.');
109
+ console.log('');
110
+ }
111
+ /** Ce que le dernier envoi a changé, en une ligne. */
112
+ function printChannelPush(push) {
113
+ const uploadedCount = push.uploaded.length;
114
+ console.log(uploadedCount === 0
115
+ ? ` canal version ${push.version} — ${push.declared} fichiers, rien à monter`
116
+ : ` canal version ${push.version} — ${uploadedCount}/${push.declared} fichier(s), ${push.uploadedBytes} o montés`);
117
+ }
118
+ /**
119
+ * Une compilation qui échoue doit se voir sur l'appareil, au lieu d'y laisser
120
+ * la page d'avant. Un canal injoignable est dit et non fatal : le serveur
121
+ * local, lui, tourne toujours.
122
+ */
123
+ async function reportBuildFailure(channel, error) {
124
+ if (channel === null) {
125
+ return;
126
+ }
127
+ try {
128
+ await channel.reportError(error instanceof Error ? error.message : String(error));
129
+ }
130
+ catch (channelFailure) {
131
+ console.error("[cadence dev] canal injoignable pour signaler l'échec :", channelFailure);
132
+ }
133
+ }
31
134
  /** Commandes qui parlent au serveur plutôt qu'à un dossier de sources. */
32
135
  const ACCOUNT_COMMANDS = new Set(['login', 'logout', 'whoami']);
33
136
  async function main() {
@@ -43,6 +146,7 @@ async function main() {
43
146
  remote: { type: 'string' },
44
147
  token: { type: 'string' },
45
148
  'app-id': { type: 'string' },
149
+ channel: { type: 'boolean', default: false },
46
150
  help: { type: 'boolean', default: false },
47
151
  },
48
152
  });
@@ -90,20 +194,32 @@ async function main() {
90
194
  }
91
195
  if (command === 'dev') {
92
196
  const outDir = values.out ?? path.join(miniappDir, 'dist');
197
+ const distDir = path.resolve(outDir);
198
+ const build = () => buildMiniApp({ miniappDir, outDir, minify: false, zip: false });
199
+ /* Le canal s'ouvre après la première compilation : son nom d'application
200
+ se résout sur le slug du manifeste, que seule la compilation rend. */
201
+ const first = await build();
202
+ const channel = values.channel === true ? await openChannelFor(first, distDir, values['app-id']) : null;
93
203
  const rebuild = async () => {
94
- await buildMiniApp({ miniappDir, outDir, minify: false, zip: false });
204
+ let summary;
205
+ try {
206
+ summary = await build();
207
+ }
208
+ catch (error) {
209
+ await reportBuildFailure(channel, error);
210
+ throw error;
211
+ }
212
+ if (channel !== null) {
213
+ printChannelPush(await channel.push(summary.manifest));
214
+ }
95
215
  };
96
- await rebuild();
97
216
  const port = values.port === undefined ? DEFAULT_DEV_PORT : Number(values.port);
98
- const server = startDevServer({
99
- distDir: path.resolve(outDir),
100
- watchDir: miniappDir,
101
- port,
102
- rebuild,
103
- });
104
- console.log(`mini dev — ${server.url}`);
105
- console.log(' navigateur : mock natif intégré (Échap = retour)');
106
- console.log(` app hôte : pointer le conteneur Flutter sur ${server.url}index.html`);
217
+ const server = startDevServer({ distDir, watchDir: miniappDir, port, rebuild });
218
+ printDevAddresses(server, port);
219
+ if (channel !== null) {
220
+ printChannelPairing(channel);
221
+ printChannelPush(await channel.push(first.manifest));
222
+ }
107
223
  return;
108
224
  }
109
225
  exitWith(`commande inconnue '${command}'\n\n${HELP}`);
@@ -184,6 +300,11 @@ function printSummary(summary) {
184
300
  }
185
301
  console.log(` engine.js : ${engineGzipKo} ko gzip (${describeEngineBudget(budgetVerdict)})`);
186
302
  console.log(` app.js : ${appGzipKo} ko gzip`);
303
+ if (summary.assets.length > 0) {
304
+ const assetsKo = (summary.assets.reduce((total, asset) => total + asset.bytes, 0) / 1024).toFixed(1);
305
+ const plural = summary.assets.length > 1 ? 's' : '';
306
+ console.log(` actifs : ${summary.assets.length} fichier${plural}, ${assetsKo} ko`);
307
+ }
187
308
  if (summary.zipFile !== null) {
188
309
  console.log(` archive : ${summary.zipFile}`);
189
310
  }
@@ -0,0 +1,61 @@
1
+ import type { FetchLike } from './publish/distribution-client.js';
2
+ /** Un canal ouvert, tel que le serveur le décrit. */
3
+ export interface OpenedDevChannel {
4
+ /** Le code tel qu'il voyage dans une URL. */
5
+ readonly code: string;
6
+ /** Le même, écrit pour être lu à voix haute et recopié. */
7
+ readonly displayCode: string;
8
+ /** L'adresse que l'appareil interroge. */
9
+ readonly pollUrl: string;
10
+ readonly expiresAt: string | null;
11
+ }
12
+ /** L'état du canal après un envoi de manifeste. */
13
+ export interface PushedBundle {
14
+ readonly version: number;
15
+ /**
16
+ * Les chemins que le canal ne tient pas à l'empreinte déclarée. Au second
17
+ * envoi d'un fichier inchangé, la liste est vide.
18
+ */
19
+ readonly missingAssets: readonly string[];
20
+ }
21
+ export interface DevChannelClientOptions {
22
+ readonly remoteUrl: string;
23
+ readonly token: string;
24
+ readonly fetch?: FetchLike;
25
+ }
26
+ /** Le serveur a refusé une opération du canal, pour une raison qu'il explique. */
27
+ export declare class DevChannelRejectedError extends Error {
28
+ readonly status: number;
29
+ readonly body: string;
30
+ readonly name = "DevChannelRejectedError";
31
+ constructor(status: number, body: string);
32
+ }
33
+ /**
34
+ * Le canal de développement, vu du CLI (ADR-038).
35
+ *
36
+ * Pousser ici ne crée aucune version : l'emplacement est éphémère, et le code
37
+ * court suffit à l'appareil qui le lit. Une méthode par intention, et des
38
+ * erreurs typées — aucun appelant n'a à lire un code HTTP.
39
+ */
40
+ export declare class DevChannelClient {
41
+ constructor(options: DevChannelClientOptions);
42
+ private readonly remoteUrl;
43
+ private readonly token;
44
+ private readonly fetch;
45
+ /** Ouvre un canal pour cette application, et rend son code. */
46
+ open(appId: string): Promise<OpenedDevChannel>;
47
+ /**
48
+ * Remplace le manifeste du canal, et rend ce qui lui manque encore.
49
+ *
50
+ * Le manifeste porte la carte d'intégrité du bundle — `assets`, une empreinte
51
+ * par chemin —, dont le serveur déduit sa réponse. Un manifeste sans cette
52
+ * carte vide le canal de ses fichiers.
53
+ */
54
+ pushBundle(code: string, manifest: Record<string, unknown>): Promise<PushedBundle>;
55
+ /** Dépose un fichier du bundle, que le manifeste courant doit avoir déclaré. */
56
+ putAsset(code: string, assetPath: string, bytes: Uint8Array, contentType: string): Promise<void>;
57
+ /** Fait porter une erreur de compilation à l'écran de l'appareil. */
58
+ reportError(code: string, message: string): Promise<void>;
59
+ private send;
60
+ private rejectionFor;
61
+ }
@@ -0,0 +1,168 @@
1
+ import { normalizeRemoteUrl } from "./publish/credentials.js";
2
+ import { InvalidTokenError, RemoteUnreachableError } from "./publish/publish-errors.js";
3
+ const HTTP_UNAUTHORIZED = 401;
4
+ const HTTP_FORBIDDEN = 403;
5
+ const CHANNELS_ENDPOINT = '/api/v1/dev-channels';
6
+ /** Le serveur a refusé une opération du canal, pour une raison qu'il explique. */
7
+ export class DevChannelRejectedError extends Error {
8
+ status;
9
+ body;
10
+ name = 'DevChannelRejectedError';
11
+ constructor(status, body) {
12
+ super(`le serveur a refusé le canal de développement (HTTP ${status})${body === '' ? '' : ` : ${body}`}`);
13
+ this.status = status;
14
+ this.body = body;
15
+ }
16
+ }
17
+ /**
18
+ * Le canal de développement, vu du CLI (ADR-038).
19
+ *
20
+ * Pousser ici ne crée aucune version : l'emplacement est éphémère, et le code
21
+ * court suffit à l'appareil qui le lit. Une méthode par intention, et des
22
+ * erreurs typées — aucun appelant n'a à lire un code HTTP.
23
+ */
24
+ export class DevChannelClient {
25
+ constructor(options) {
26
+ this.remoteUrl = normalizeRemoteUrl(options.remoteUrl);
27
+ this.token = options.token;
28
+ this.fetch = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
29
+ }
30
+ remoteUrl;
31
+ token;
32
+ fetch;
33
+ /** Ouvre un canal pour cette application, et rend son code. */
34
+ async open(appId) {
35
+ const response = await this.send(CHANNELS_ENDPOINT, {
36
+ method: 'POST',
37
+ headers: { 'content-type': 'application/json' },
38
+ body: JSON.stringify({ appId }),
39
+ });
40
+ if (!response.ok) {
41
+ throw this.rejectionFor(response.status, await readBody(response));
42
+ }
43
+ return parseOpenedChannel(await readBody(response));
44
+ }
45
+ /**
46
+ * Remplace le manifeste du canal, et rend ce qui lui manque encore.
47
+ *
48
+ * Le manifeste porte la carte d'intégrité du bundle — `assets`, une empreinte
49
+ * par chemin —, dont le serveur déduit sa réponse. Un manifeste sans cette
50
+ * carte vide le canal de ses fichiers.
51
+ */
52
+ async pushBundle(code, manifest) {
53
+ const response = await this.send(`${CHANNELS_ENDPOINT}/${code}/bundle`, {
54
+ method: 'PUT',
55
+ headers: { 'content-type': 'application/json' },
56
+ body: JSON.stringify(manifest),
57
+ });
58
+ if (!response.ok) {
59
+ throw this.rejectionFor(response.status, await readBody(response));
60
+ }
61
+ return parsePushedBundle(await readBody(response));
62
+ }
63
+ /** Dépose un fichier du bundle, que le manifeste courant doit avoir déclaré. */
64
+ async putAsset(code, assetPath, bytes, contentType) {
65
+ const response = await this.send(`${CHANNELS_ENDPOINT}/${code}/assets/${encodeAssetPath(assetPath)}`, {
66
+ method: 'PUT',
67
+ headers: { 'content-type': contentType },
68
+ body: bytes,
69
+ });
70
+ if (!response.ok) {
71
+ throw this.rejectionFor(response.status, await readBody(response));
72
+ }
73
+ }
74
+ /** Fait porter une erreur de compilation à l'écran de l'appareil. */
75
+ async reportError(code, message) {
76
+ const response = await this.send(`${CHANNELS_ENDPOINT}/${code}/error`, {
77
+ method: 'PUT',
78
+ headers: { 'content-type': 'application/json' },
79
+ body: JSON.stringify({ message }),
80
+ });
81
+ if (!response.ok) {
82
+ throw this.rejectionFor(response.status, await readBody(response));
83
+ }
84
+ }
85
+ async send(pathname, init) {
86
+ const url = `${this.remoteUrl}${pathname}`;
87
+ try {
88
+ return await this.fetch(url, {
89
+ ...init,
90
+ headers: { ...(init.headers ?? {}), authorization: `Bearer ${this.token}` },
91
+ });
92
+ }
93
+ catch (error) {
94
+ throw new RemoteUnreachableError(url, error);
95
+ }
96
+ }
97
+ rejectionFor(status, body) {
98
+ if (status === HTTP_UNAUTHORIZED || status === HTTP_FORBIDDEN) {
99
+ return new InvalidTokenError(status);
100
+ }
101
+ return new DevChannelRejectedError(status, body);
102
+ }
103
+ }
104
+ /**
105
+ * Chaque segment est encodé, les barres obliques restent des séparateurs : le
106
+ * serveur lit le chemin du fichier dans ce qui suit `/assets/`.
107
+ */
108
+ function encodeAssetPath(assetPath) {
109
+ return assetPath.split('/').map(encodeURIComponent).join('/');
110
+ }
111
+ /**
112
+ * Le code et l'adresse d'interrogation sont indispensables : sans eux, rien ne
113
+ * peut être poussé ni lu, et un canal à moitié décrit vaut une panne.
114
+ */
115
+ function parseOpenedChannel(body) {
116
+ const parsed = parseObject(body);
117
+ const code = asText(parsed['code']);
118
+ const pollUrl = asText(parsed['pollUrl']);
119
+ if (code === null || pollUrl === null) {
120
+ throw new Error(`le serveur a ouvert un canal sans code exploitable : ${body}`);
121
+ }
122
+ return {
123
+ code,
124
+ displayCode: asText(parsed['displayCode']) ?? code,
125
+ pollUrl,
126
+ expiresAt: asText(parsed['expiresAt']),
127
+ };
128
+ }
129
+ /** La version du canal est ce qui dit à l'appareil qu'il doit relire. */
130
+ function parsePushedBundle(body) {
131
+ const parsed = parseObject(body);
132
+ const version = parsed['version'];
133
+ if (typeof version !== 'number') {
134
+ throw new Error(`le serveur n'a pas rendu la version du canal : ${body}`);
135
+ }
136
+ const missing = parsed['missingAssets'];
137
+ return {
138
+ version,
139
+ missingAssets: Array.isArray(missing) ? missing.filter(isNonEmptyText) : [],
140
+ };
141
+ }
142
+ function parseObject(body) {
143
+ let parsed;
144
+ try {
145
+ parsed = JSON.parse(body);
146
+ }
147
+ catch {
148
+ throw new Error(`réponse illisible du serveur de canal : ${body}`);
149
+ }
150
+ if (typeof parsed !== 'object' || parsed === null) {
151
+ throw new Error(`réponse inattendue du serveur de canal : ${body}`);
152
+ }
153
+ return parsed;
154
+ }
155
+ function asText(value) {
156
+ return typeof value === 'string' && value !== '' ? value : null;
157
+ }
158
+ function isNonEmptyText(value) {
159
+ return typeof value === 'string' && value !== '';
160
+ }
161
+ async function readBody(response) {
162
+ try {
163
+ return (await response.text()).trim();
164
+ }
165
+ catch {
166
+ return '';
167
+ }
168
+ }
@@ -0,0 +1,46 @@
1
+ import type { MiniAppManifest } from './manifest.js';
2
+ import type { Credentials } from './publish/credentials.js';
3
+ import { DevChannelClient } from './dev-channel-client.js';
4
+ /** Ce qu'un envoi a réellement coûté, et ce qu'il a changé. */
5
+ export interface DevChannelPush {
6
+ readonly version: number;
7
+ /** Fichiers déclarés par le bundle. */
8
+ readonly declared: number;
9
+ /** Ceux que le canal n'avait pas, et qui viennent de monter. */
10
+ readonly uploaded: readonly string[];
11
+ readonly uploadedBytes: number;
12
+ }
13
+ /** Un canal ouvert, prêt à recevoir les compilations successives. */
14
+ export interface DevChannelSession {
15
+ readonly code: string;
16
+ readonly displayCode: string;
17
+ readonly pollUrl: string;
18
+ readonly expiresAt: string | null;
19
+ /**
20
+ * Déclare le bundle compilé, puis envoie les seuls fichiers qui manquent au
21
+ * canal. Un enregistrement qui ne change qu'un fichier n'en monte qu'un.
22
+ */
23
+ push(manifest: MiniAppManifest): Promise<DevChannelPush>;
24
+ /** Fait porter une erreur de compilation à l'écran de l'appareil. */
25
+ reportError(message: string): Promise<void>;
26
+ }
27
+ export interface OpenDevChannelOptions {
28
+ /** Le dossier compilé, dont chaque fichier est déclaré au canal. */
29
+ readonly distDir: string;
30
+ /** Ouvrir le canal de cette application-ci, au lieu de résoudre le slug. */
31
+ readonly appId?: string;
32
+ /** Le slug du manifeste, employé quand `appId` est absent. */
33
+ readonly slug: string;
34
+ /** Identifiants explicites, sinon ceux de `mini login`. */
35
+ readonly credentials?: Credentials;
36
+ /** Fabriques injectées : les tests n'ont alors aucun réseau à simuler. */
37
+ readonly createClient?: (credentials: Credentials) => DevChannelClient;
38
+ readonly resolveAppId?: (credentials: Credentials, slug: string) => Promise<string>;
39
+ }
40
+ /**
41
+ * Ouvre un canal de développement et rend de quoi l'alimenter (ADR-038).
42
+ *
43
+ * Le canal ne crée aucune version, et rien de ce qu'il porte ne s'installe sur
44
+ * l'appareil : ce qui tient la place d'une signature est l'éphémère.
45
+ */
46
+ export declare function openDevChannel(options: OpenDevChannelOptions): Promise<DevChannelSession>;