pi-pocket 0.25.0 → 0.26.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.
Files changed (85) hide show
  1. package/AGENTS.md +2 -0
  2. package/README.md +5 -3
  3. package/docs/architecture.md +21 -0
  4. package/docs/design/design-mode.md +108 -0
  5. package/docs/design/notes-a.md +106 -0
  6. package/docs/design/notes-b.md +123 -0
  7. package/docs/design/notes-c.md +92 -0
  8. package/docs/design/notes-d.md +78 -0
  9. package/docs/design/release-notes-design.md +46 -0
  10. package/docs/extensions/browser-modules.md +2 -0
  11. package/docs/extensions/policies/api-stability.md +2 -0
  12. package/docs/extensions/reference/api-versions.md +1 -0
  13. package/docs/extensions/reference/host.md +1 -1
  14. package/docs/extensions/reference/limits.md +4 -0
  15. package/docs/extensions/reference/names.md +2 -2
  16. package/docs/extensions/reference/pocket.md +38 -0
  17. package/docs/features.md +19 -5
  18. package/docs/map.md +75 -54
  19. package/docs/release-notes.md +1 -1
  20. package/docs/self-editing.md +1 -1
  21. package/docs/systemd.md +1 -1
  22. package/npm-shrinkwrap.json +2 -2
  23. package/package.json +1 -1
  24. package/src/launcher/main.ts +20 -9
  25. package/src/server/app.ts +113 -4
  26. package/src/server/background.ts +3 -3
  27. package/src/server/cache-keeper.ts +605 -0
  28. package/src/server/compaction.ts +68 -15
  29. package/src/server/design/bundle.ts +65 -0
  30. package/src/server/design/export.ts +118 -0
  31. package/src/server/design/files.ts +49 -0
  32. package/src/server/design/guide.ts +56 -0
  33. package/src/server/design/index.ts +232 -0
  34. package/src/server/design/pptx.ts +304 -0
  35. package/src/server/design/render.ts +593 -0
  36. package/src/server/design/system.ts +248 -0
  37. package/src/server/docs.ts +55 -0
  38. package/src/server/extensions/artifacts.ts +202 -18
  39. package/src/server/extensions/design/canvas.js +304 -0
  40. package/src/server/extensions/design/comments.js +15 -0
  41. package/src/server/extensions/design/data.js +263 -0
  42. package/src/server/extensions/design/devices.js +70 -0
  43. package/src/server/extensions/design/docks.js +647 -0
  44. package/src/server/extensions/design/edits.js +37 -0
  45. package/src/server/extensions/design/index.js +326 -0
  46. package/src/server/extensions/design/messages.js +92 -0
  47. package/src/server/extensions/design/parts.js +160 -0
  48. package/src/server/extensions/design/state.js +146 -0
  49. package/src/server/extensions/design/style.css +1332 -0
  50. package/src/server/extensions/design/tweaks.js +161 -0
  51. package/src/server/extensions/design/views.js +375 -0
  52. package/src/server/extensions/design/workspace.js +723 -0
  53. package/src/server/extensions/design.ts +620 -0
  54. package/src/server/extensions/plan.ts +11 -9
  55. package/src/server/extensions/prompt.ts +11 -3
  56. package/src/server/extensions/subagents.ts +7 -1
  57. package/src/server/extensions/updates/index.js +16 -6
  58. package/src/server/extensions/updates.ts +2 -2
  59. package/src/server/http/artifact-assets.ts +216 -0
  60. package/src/server/http/artifact-inspect.ts +1281 -0
  61. package/src/server/http/artifacts.ts +89 -14
  62. package/src/server/http/conversation-routes.ts +46 -1
  63. package/src/server/http.ts +12 -4
  64. package/src/server/main.ts +4 -0
  65. package/src/server/npm-install.ts +82 -0
  66. package/src/server/npm-update.ts +100 -0
  67. package/src/server/reload.ts +5 -0
  68. package/src/server/room.ts +2 -0
  69. package/src/server/spend.ts +73 -9
  70. package/src/server/update-state.ts +257 -8
  71. package/src/server/updates.ts +268 -33
  72. package/src/server/zip.ts +163 -0
  73. package/types/pocket.d.ts +32 -0
  74. package/web/activity-fold.js +28 -0
  75. package/web/artifact-bridge.js +506 -82
  76. package/web/extension-ui.js +21 -1
  77. package/web/pip.js +46 -9
  78. package/web/sessions.js +1 -1
  79. package/web/sheets/appearance.js +10 -0
  80. package/web/sheets/viewers.js +26 -1
  81. package/web/style.css +11 -0
  82. package/web/taps.js +26 -0
  83. package/web/theme.js +6 -0
  84. package/web/transcript.js +19 -10
  85. package/src/server/http/public.ts +0 -30
@@ -1,5 +1,5 @@
1
1
  /**
2
- * What an update of Pi Pocket's own checkout leaves on disk, in `.pocket-update/` in the checkout: the update under way
2
+ * Update state in `.pocket-update/` in a checkout, or `.pi-pocket-update/` beside an npm package: the update under way
3
3
  * (`pending.json`), how the last one ended (`last.json`), the packages it installs (`staging/`), and the ones it
4
4
  * replaced (`previous/`). The server writes them (`updates.ts`); the launcher reads them when a server it started after
5
5
  * an update stops before it is ready, and goes back to the version before (`rollBackUpdate`). It imports only Node's
@@ -17,27 +17,29 @@ import {
17
17
  rmSync,
18
18
  writeFileSync,
19
19
  } from "node:fs";
20
- import { dirname, join, relative } from "node:path";
20
+ import { basename, dirname, join, relative, resolve } from "node:path";
21
21
 
22
22
  /** The folder in the checkout, which `.gitignore` leaves out. */
23
23
  export const UPDATE_DIR = ".pocket-update";
24
24
 
25
- /** An update under way: from one commit to another, written before the checkout changes. */
25
+ /** An update under way, written before staging or changing the live package or checkout. */
26
26
  export type PendingUpdate = {
27
27
  v: 1;
28
+ /** Omitted by older git update records. */
29
+ kind?: "npm-global";
28
30
  tag: string;
29
31
  fromVersion: string;
30
32
  toVersion: string;
31
- /** The commit before, and the release's. */
33
+ /** The commit before, and the release's. Empty strings for npm updates. */
32
34
  from: string;
33
35
  to: string;
34
36
  /** The branch the update moves, or null for a detached checkout. */
35
37
  branch: string | null;
36
- /** New packages went in, and the ones before wait in `previous/`. */
38
+ /** New dependencies (git) or the whole new package (npm) went in. */
37
39
  modules: boolean;
38
40
  /** The release notes warn of a step that cannot be undone: the launcher does not go back by itself. */
39
41
  oneWay: boolean;
40
- /** "switching" once git may have changed files: a stop then can leave some of the release's files. */
42
+ /** "switching" before git can change files, or before the npm package's first rename. */
41
43
  phase: "packages" | "switching";
42
44
  at: number;
43
45
  };
@@ -56,7 +58,17 @@ export type UpdateOutcome = {
56
58
  };
57
59
 
58
60
  export function updatePaths(appRoot: string) {
59
- const dir = join(appRoot, UPDATE_DIR);
61
+ appRoot = resolve(appRoot);
62
+ const parent = dirname(appRoot);
63
+ const npmPackage =
64
+ basename(parent) === "node_modules" ||
65
+ (basename(parent).startsWith("@") && basename(dirname(parent)) === "node_modules");
66
+ const sibling = join(parent, ".pi-pocket-update");
67
+ // A global root can resolve through a symlink to a folder not named node_modules. The writer
68
+ // marks that exact package root; the launcher needs neither npm nor the live package to find it.
69
+ const markedGlobal = readJson(join(sibling, "npm-global.json"))?.appRoot === appRoot;
70
+ // npm ignores dot-prefixed siblings. State must survive replacement or removal of the package.
71
+ const dir = npmPackage || markedGlobal ? sibling : join(appRoot, UPDATE_DIR);
60
72
 
61
73
  return {
62
74
  dir,
@@ -103,12 +115,17 @@ export function readPending(appRoot: string): PendingUpdate | undefined {
103
115
  return undefined;
104
116
  }
105
117
 
106
- if (!COMMIT.test(from) || !COMMIT.test(to)) {
118
+ if (raw.kind === "npm-global") {
119
+ if (!text(raw.fromVersion) || !text(raw.toVersion)) {
120
+ return undefined;
121
+ }
122
+ } else if (raw.kind !== undefined || !COMMIT.test(from) || !COMMIT.test(to)) {
107
123
  return undefined;
108
124
  }
109
125
 
110
126
  return {
111
127
  v: 1,
128
+ ...(raw.kind === "npm-global" ? { kind: "npm-global" as const } : {}),
112
129
  tag: text(raw.tag) ?? "",
113
130
  fromVersion: text(raw.fromVersion) ?? "",
114
131
  toVersion: text(raw.toVersion) ?? "",
@@ -124,6 +141,13 @@ export function readPending(appRoot: string): PendingUpdate | undefined {
124
141
  }
125
142
 
126
143
  export function writePending(appRoot: string, pending: PendingUpdate): void {
144
+ if (pending.kind === "npm-global") {
145
+ const root = resolve(appRoot);
146
+ const marker = join(dirname(root), ".pi-pocket-update", "npm-global.json");
147
+
148
+ writeJson(marker, { v: 1, appRoot: root });
149
+ }
150
+
127
151
  writeJson(updatePaths(appRoot).pending, pending);
128
152
  }
129
153
 
@@ -253,6 +277,226 @@ export function restoreModules(appRoot: string): boolean {
253
277
  return true;
254
278
  }
255
279
 
280
+ /** The package npm installs with an isolated global prefix. Its dependencies stay inside it. */
281
+ export function stagedPackagePath(appRoot: string): string {
282
+ const { staging } = updatePaths(appRoot);
283
+
284
+ return process.platform === "win32"
285
+ ? join(staging, "node_modules", "pi-pocket")
286
+ : join(staging, "lib", "node_modules", "pi-pocket");
287
+ }
288
+
289
+ /** Read without importing package code: the launcher can use this after a package rename. */
290
+ function packageVersion(root: string): string | undefined {
291
+ const manifest = readJson(join(root, "package.json"));
292
+
293
+ return manifest?.name === "pi-pocket" ? text(manifest.version) : undefined;
294
+ }
295
+
296
+ function npmPending(appRoot: string): PendingUpdate {
297
+ const pending = readPending(appRoot);
298
+
299
+ if (pending?.kind !== "npm-global") {
300
+ throw new Error("No npm global update is pending.");
301
+ }
302
+
303
+ return pending;
304
+ }
305
+
306
+ /** Swap whole packages on the same file system. The global bin link keeps its original target. */
307
+ export function swapInPackage(appRoot: string): void {
308
+ const pending = npmPending(appRoot);
309
+ const paths = updatePaths(appRoot);
310
+ const fresh = stagedPackagePath(appRoot);
311
+
312
+ if (packageVersion(fresh) !== pending.toVersion) {
313
+ throw new Error("The staged package does not match the pending version.");
314
+ }
315
+
316
+ if (
317
+ pending.phase !== "packages" ||
318
+ pending.modules ||
319
+ packageVersion(appRoot) !== pending.fromVersion
320
+ ) {
321
+ throw new Error("The live package changed, or this package swap already started.");
322
+ }
323
+
324
+ // A previous one-way update can leave its old package for manual recovery. Keep it without
325
+ // blocking a later update or deleting a package that the owner may still need.
326
+ for (const name of ["previous", "failed"] as const) {
327
+ if (existsSync(paths[name])) {
328
+ const kept = join(paths.dir, "kept");
329
+
330
+ mkdirSync(kept, { recursive: true });
331
+ const folder = mkdtempSync(join(kept, `npm-${name}-`));
332
+
333
+ renameSync(paths[name], join(folder, "package"));
334
+ }
335
+ }
336
+
337
+ writePending(appRoot, { ...pending, phase: "switching" });
338
+
339
+ // Keep these renames synchronous and adjacent: only a whole-process stop can interrupt them.
340
+ try {
341
+ renameSync(appRoot, paths.previous);
342
+ renameSync(fresh, appRoot);
343
+ } catch (error) {
344
+ if (!existsSync(appRoot) && existsSync(paths.previous)) {
345
+ renameSync(paths.previous, appRoot);
346
+ }
347
+
348
+ throw error;
349
+ }
350
+
351
+ writePending(appRoot, { ...pending, phase: "switching", modules: true });
352
+ }
353
+
354
+ /** Repair a missing live package before the launcher spawns a server or the server loads its app modules. */
355
+ export function restoreMissingNpmPackage(appRoot: string): boolean {
356
+ const pending = readPending(appRoot);
357
+
358
+ if (pending?.kind !== "npm-global" || existsSync(appRoot)) {
359
+ return false;
360
+ }
361
+
362
+ const paths = updatePaths(appRoot);
363
+ const fresh = stagedPackagePath(appRoot);
364
+ const previous = packageVersion(paths.previous);
365
+ const failed = packageVersion(paths.failed);
366
+
367
+ if (existsSync(paths.previous) && previous !== pending.fromVersion) {
368
+ throw new Error("The previous npm package changed; it was kept for manual recovery.");
369
+ }
370
+
371
+ // Do not restore an older version after a warning release may have changed the data.
372
+ const keepNew = pending.oneWay && (pending.modules || failed === pending.toVersion);
373
+ const source =
374
+ !keepNew && previous === pending.fromVersion
375
+ ? paths.previous
376
+ : keepNew && failed === pending.toVersion
377
+ ? paths.failed
378
+ : packageVersion(fresh) === pending.toVersion
379
+ ? fresh
380
+ : undefined;
381
+
382
+ if (source === undefined) {
383
+ throw new Error("The live npm package is missing, with no safe copy to restore.");
384
+ }
385
+
386
+ if (source !== paths.previous) {
387
+ writePending(appRoot, { ...pending, phase: "switching", modules: true });
388
+ }
389
+
390
+ renameSync(source, appRoot);
391
+
392
+ return true;
393
+ }
394
+
395
+ /** Restore a whole npm package, including its dependencies, without invoking npm or a network. */
396
+ export function restorePackage(appRoot: string): boolean {
397
+ const pending = npmPending(appRoot);
398
+ const paths = updatePaths(appRoot);
399
+
400
+ // Staging can fail before a swap starts. An older one-way update may have left an unrelated
401
+ // previous package: the live version is already right, so leave both packages untouched.
402
+ // This also handles a stop after the final restore rename.
403
+ if (packageVersion(appRoot) === pending.fromVersion) {
404
+ return true;
405
+ }
406
+
407
+ if (!existsSync(paths.previous)) {
408
+ return false;
409
+ }
410
+
411
+ if (packageVersion(paths.previous) !== pending.fromVersion) {
412
+ throw new Error("The previous package does not match the pending version; it was kept.");
413
+ }
414
+
415
+ if (existsSync(appRoot)) {
416
+ if (packageVersion(appRoot) !== pending.toVersion || existsSync(paths.failed)) {
417
+ throw new Error("The live package changed during recovery; no package was removed.");
418
+ }
419
+
420
+ renameSync(appRoot, paths.failed);
421
+ }
422
+
423
+ renameSync(paths.previous, appRoot);
424
+
425
+ return true;
426
+ }
427
+
428
+ /** Startup completed: record success, or recover an update that stopped before the swap completed. */
429
+ export function finishNpmPending(
430
+ appRoot: string,
431
+ pending: PendingUpdate,
432
+ now = Date.now(),
433
+ ): UpdateOutcome {
434
+ if (pending.kind !== "npm-global") {
435
+ throw new Error("This is not an npm global update.");
436
+ }
437
+
438
+ const current = packageVersion(appRoot);
439
+
440
+ // A manual npm reinstall can finish before a staged update switches packages. Keep any
441
+ // unrelated backup, and clear that stale record without replacing the running package.
442
+ if (
443
+ current !== undefined &&
444
+ current !== pending.fromVersion &&
445
+ (current !== pending.toVersion || pending.phase === "packages")
446
+ ) {
447
+ return finishPending(
448
+ appRoot,
449
+ pending,
450
+ false,
451
+ `The npm package changed during the update to ${pending.toVersion}. Pi Pocket started at ${current}, so no package was replaced during recovery.`,
452
+ now,
453
+ );
454
+ }
455
+
456
+ if (pending.phase === "switching" && current === pending.toVersion) {
457
+ return finishPending(
458
+ appRoot,
459
+ pending,
460
+ true,
461
+ `Pi Pocket updated from ${pending.fromVersion} to ${pending.toVersion}.`,
462
+ now,
463
+ );
464
+ }
465
+
466
+ return rollBackNpm(appRoot, pending, now);
467
+ }
468
+
469
+ function rollBackNpm(appRoot: string, pending: PendingUpdate, now: number): UpdateOutcome {
470
+ const to = pending.toVersion;
471
+ const from = pending.fromVersion;
472
+ const paths = updatePaths(appRoot);
473
+ // A previous package plus a live release (or one set aside during recovery) means it may have run.
474
+ const mayHaveRun =
475
+ packageVersion(appRoot) === to || packageVersion(paths.failed) === to || pending.modules;
476
+
477
+ if (pending.oneWay && mayHaveRun) {
478
+ return finishPending(
479
+ appRoot,
480
+ pending,
481
+ false,
482
+ `${to} did not start. Its release notes warn of a step that cannot be undone, so Pi Pocket did not go back to ${from} by itself: read the release notes, and the server's log.`,
483
+ now,
484
+ );
485
+ }
486
+
487
+ if (!restorePackage(appRoot)) {
488
+ throw new Error("The previous npm package is missing. The pending update was kept.");
489
+ }
490
+
491
+ return finishPending(
492
+ appRoot,
493
+ pending,
494
+ false,
495
+ `The update to ${to} did not finish, so Pi Pocket went back to ${from}. The server's log says why.`,
496
+ now,
497
+ );
498
+ }
499
+
256
500
  /** The checkout's branch, null when detached, undefined when git cannot say. */
257
501
  function branchOf(appRoot: string): string | null | undefined {
258
502
  const head = gitSync(appRoot, ["symbolic-ref", "--quiet", "--short", "HEAD"]);
@@ -577,6 +821,11 @@ export function rollBackUpdate(appRoot: string, now = Date.now()): string | unde
577
821
  return undefined;
578
822
  }
579
823
 
824
+ // npm recovery must retain the pending record if a rename fails. The next start can retry it.
825
+ if (pending.kind === "npm-global") {
826
+ return rollBackNpm(appRoot, pending, now).message;
827
+ }
828
+
580
829
  try {
581
830
  return rollBack(appRoot, pending, now);
582
831
  } catch (error) {