anhedral 0.11.2 → 0.13.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 (102) hide show
  1. package/README.md +171 -18
  2. package/dist/bin.js +48 -493
  3. package/dist/capabilities.d.ts +3 -3
  4. package/dist/capability-contract.js +16 -1
  5. package/dist/cli-arguments.d.ts +8 -0
  6. package/dist/cli-arguments.js +32 -0
  7. package/dist/cli-commands.d.ts +3 -0
  8. package/dist/cli-commands.js +114 -0
  9. package/dist/cli-delivery.d.ts +3 -0
  10. package/dist/cli-delivery.js +172 -0
  11. package/dist/cli-output.js +231 -205
  12. package/dist/command-schema.js +8 -2
  13. package/dist/command.js +9 -11
  14. package/dist/delivery-evidence.d.ts +62 -0
  15. package/dist/delivery-evidence.js +186 -0
  16. package/dist/delivery.d.ts +3 -40
  17. package/dist/delivery.js +7 -182
  18. package/dist/dependencies.d.ts +7 -1
  19. package/dist/dependencies.js +15 -1
  20. package/dist/index.d.ts +1 -0
  21. package/dist/index.js +1 -0
  22. package/dist/mobile-delivery.d.ts +21 -44
  23. package/dist/mobile-delivery.js +127 -80
  24. package/dist/platforms/mobile.d.ts +1 -1
  25. package/dist/platforms/mobile.js +44 -3
  26. package/dist/project-state.js +4 -1
  27. package/dist/provider-auth.js +9 -3
  28. package/dist/providers/adapters.js +9 -3
  29. package/dist/providers/runtime.js +11 -0
  30. package/dist/readiness.js +4 -2
  31. package/dist/registry/add.js +40 -7
  32. package/dist/registry/options.js +12 -0
  33. package/dist/registry/presets.d.ts +4 -0
  34. package/dist/registry/presets.js +41 -0
  35. package/dist/registry/resolve.d.ts +3 -1
  36. package/dist/registry/resolve.js +40 -14
  37. package/dist/registry/types.d.ts +1 -0
  38. package/dist/registry/usage.js +1 -1
  39. package/dist/runtime-policy.js +4 -1
  40. package/dist/scaffold/api.js +10 -2
  41. package/dist/scaffold/auth.d.ts +1 -1
  42. package/dist/scaffold/auth.js +22 -6
  43. package/dist/scaffold/backend.d.ts +6 -0
  44. package/dist/scaffold/backend.js +224 -0
  45. package/dist/scaffold/billing-config.d.ts +1 -0
  46. package/dist/scaffold/billing-config.js +73 -0
  47. package/dist/scaffold/billing-contracts.d.ts +2 -0
  48. package/dist/scaffold/billing-contracts.js +48 -0
  49. package/dist/scaffold/billing-providers.d.ts +1 -0
  50. package/dist/scaffold/billing-providers.js +249 -0
  51. package/dist/scaffold/billing-schema.d.ts +1 -0
  52. package/dist/scaffold/billing-schema.js +34 -0
  53. package/dist/scaffold/billing-security.d.ts +1 -0
  54. package/dist/scaffold/billing-security.js +46 -0
  55. package/dist/scaffold/billing-server.d.ts +1 -0
  56. package/dist/scaffold/billing-server.js +139 -0
  57. package/dist/scaffold/billing-store.d.ts +1 -0
  58. package/dist/scaffold/billing-store.js +72 -0
  59. package/dist/scaffold/billing.d.ts +2 -0
  60. package/dist/scaffold/billing.js +216 -0
  61. package/dist/scaffold/cloudflare-services.d.ts +8 -0
  62. package/dist/scaffold/cloudflare-services.js +198 -0
  63. package/dist/scaffold/compose.js +2 -0
  64. package/dist/scaffold/database.js +19 -2
  65. package/dist/scaffold/documentation.js +11 -6
  66. package/dist/scaffold/expo-auth.d.ts +3 -0
  67. package/dist/scaffold/expo-auth.js +192 -0
  68. package/dist/scaffold/expo-billing.d.ts +3 -0
  69. package/dist/scaffold/expo-billing.js +292 -0
  70. package/dist/scaffold/expo-runtime.d.ts +3 -0
  71. package/dist/scaffold/expo-runtime.js +134 -0
  72. package/dist/scaffold/integrations.d.ts +2 -1
  73. package/dist/scaffold/integrations.js +7 -2
  74. package/dist/scaffold/stream.d.ts +2 -0
  75. package/dist/scaffold/stream.js +114 -0
  76. package/dist/scaffold/void.js +13 -5
  77. package/dist/scaffold/web.js +2 -0
  78. package/dist/scaffold/workspace.js +6 -1
  79. package/dist/service-readers.js +1 -1
  80. package/dist/services-command.js +8 -6
  81. package/dist/ship.d.ts +15 -15
  82. package/dist/ship.js +3 -1
  83. package/dist/stack-registry.d.ts +13 -2
  84. package/dist/stack-registry.js +152 -16
  85. package/dist/transaction-lock.d.ts +15 -0
  86. package/dist/transaction-lock.js +227 -0
  87. package/dist/transaction.js +2 -208
  88. package/dist/vercel-project.d.ts +101 -0
  89. package/dist/vercel-project.js +305 -0
  90. package/dist/vercel.d.ts +3 -36
  91. package/dist/vercel.js +3 -300
  92. package/dist/version.d.ts +1 -1
  93. package/dist/version.js +1 -1
  94. package/docs/anhedral-stack.md +122 -0
  95. package/docs/software-factory.md +402 -7
  96. package/docs/stack-standard.md +226 -49
  97. package/docs/verification.md +557 -0
  98. package/package.json +7 -7
  99. package/docs/cli-design.md +0 -67
  100. package/docs/plugin-ui.md +0 -102
  101. package/docs/provider-configuration.md +0 -116
  102. package/docs/void-verification.md +0 -185
@@ -1,3 +1,4 @@
1
+ import { scaffoldCloudflareTransport, scaffoldAnalyticsEngine, scaffoldImages, scaffoldRealtimeKit, scaffoldVideo, } from './scaffold/cloudflare-services.js';
1
2
  import { usesVoidSelection } from './runtime-policy.js';
2
3
  import { scaffoldStyling } from './scaffold/styling.js';
3
4
  import { resourceName } from './render.js';
@@ -7,17 +8,33 @@ import { GENERATOR_VERSION } from './version.js';
7
8
  import { scaffoldWeb } from './scaffold/web.js';
8
9
  import { scaffoldApi } from './scaffold/api.js';
9
10
  import { scaffoldDatabase } from './scaffold/database.js';
11
+ import { scaffoldStream } from './scaffold/stream.js';
10
12
  import { scaffoldNeonRealtime } from './scaffold/neon-realtime.js';
11
13
  import { scaffoldBetterAuth, scaffoldClerk } from './scaffold/auth.js';
12
14
  import { scaffoldRealtime, scaffoldQueues, scaffoldCron, scaffoldWorkflows, } from './scaffold/services.js';
13
15
  import { scaffoldExpo } from './platforms/mobile.js';
14
16
  import { scaffoldElectron } from './platforms/desktop.js';
15
17
  import { scaffoldWxt } from './platforms/extension.js';
16
- import { scaffoldPrivateFiles, scaffoldRevenueCat } from './scaffold/integrations.js';
18
+ import { scaffoldPrivateFiles, scaffoldStripe, scaffoldRevenueCat, } from './scaffold/integrations.js';
17
19
  import { sharedPackage } from './scaffold/files.js';
18
20
  function requirements(purpose, tools, access, credentials, resources, verify) {
19
21
  return { purpose, tools, access, credentials, resources, verify };
20
22
  }
23
+ function billingDependencies({ has }) {
24
+ return [
25
+ 'hono',
26
+ has('neon') ? 'neon' : 'd1',
27
+ has('clerk') ? 'clerk' : 'better-auth',
28
+ ...(has('expo') ? ['expo'] : []),
29
+ ];
30
+ }
31
+ const BILLING_ENVIRONMENT_KEYS = [
32
+ 'BILLING_ORIGIN',
33
+ 'BILLING_ENVIRONMENT',
34
+ 'BILLING_PLANS_JSON',
35
+ 'BILLING_ENTITLEMENTS_JSON',
36
+ 'BILLING_PREMIUM_ENTITLEMENT',
37
+ ];
21
38
  function packageSource(name, source, dependencies) {
22
39
  return { name, source, dependencies };
23
40
  }
@@ -61,11 +78,17 @@ const PRODUCT_ITEMS = defineItems({
61
78
  },
62
79
  expo: {
63
80
  type: 'application',
64
- description: 'Expo mobile application with native UI',
81
+ description: 'Universal Expo web, iOS and Android client with a Cloudflare asset/API gateway',
65
82
  targets: ['apps/mobile'],
66
83
  registryDependencies: ['workspace', 'typescript', 'eslint', 'styling'],
67
- setup: requirements('Mobile application', ['Expo/EAS CLI', 'Xcode or Android SDK'], ['Client-owned Apple/Google developer accounts for store delivery'], ['Platform signing credentials; EAS access when used'], ['Expo app; native adapters, signing, store configuration'], ['Native simulator/device flows and signed native build; web export alone is insufficient']),
84
+ setup: requirements('Universal web, iOS and Android application', ['Browser control', 'Wrangler'], ['For requested native distribution only: client-owned Apple/Google developer accounts'], ['For requested native builds only: platform signing credentials and EAS access when used'], [
85
+ 'Expo universal client, Cloudflare web assets/API gateway; native adapters, signing and store configuration',
86
+ ], [
87
+ 'Static web export/runtime; requested native delivery additionally needs simulator/device and signed-build acceptance',
88
+ ]),
68
89
  install: scaffoldExpo,
90
+ environment: [],
91
+ resolveEnvironment: ({ has }) => (has('hono') ? ['EXPO_PUBLIC_API_URL'] : []),
69
92
  },
70
93
  electron: {
71
94
  type: 'application',
@@ -194,8 +217,16 @@ export interface LocalDataStore {
194
217
  fallbackDependency: 'd1',
195
218
  environment: ['BETTER_AUTH_SECRET', 'BETTER_AUTH_URL'],
196
219
  runtime: 'server',
197
- resolveDependencies: ({ has }) => [has('neon') ? 'neon' : 'd1'],
198
- resolveTargets: ({ runtimeApp }) => ['packages/auth', 'packages/db', `apps/${runtimeApp}`],
220
+ resolveDependencies: ({ has }) => [
221
+ has('neon') ? 'neon' : 'd1',
222
+ ...(has('expo') ? ['expo'] : []),
223
+ ],
224
+ resolveTargets: ({ runtimeApp, has }) => [
225
+ 'packages/auth',
226
+ 'packages/db',
227
+ `apps/${runtimeApp}`,
228
+ ...(has('expo') ? ['apps/mobile'] : []),
229
+ ],
199
230
  },
200
231
  r2: {
201
232
  type: 'integration',
@@ -231,6 +262,21 @@ export interface LocalDataStore {
231
262
  setup: requirements('Rooms and collaboration', ['Wrangler', 'Browser control'], ['Cloudflare Durable Objects deployment access'], [], ['Realtime Worker, Durable Object namespace/migration and WebSocket authorization'], ['Authorized room isolation, disconnect/reconnect and deployed WebSockets']),
232
263
  install: scaffoldRealtime,
233
264
  },
265
+ stream: {
266
+ type: 'integration',
267
+ description: 'Cloudflare Stream one-to-many live video with WHIP ingest and WHEP playback (GA)',
268
+ targets: ['packages/stream'],
269
+ runtime: 'server',
270
+ environment: ['STREAM_ACCOUNT_ID', 'STREAM_API_TOKEN'],
271
+ setup: requirements('Ultra-low latency one-to-many live video', ['Cloudflare Stream API or dashboard', 'Browser control'], ['Client-owned Cloudflare account with Stream enabled; usage-based delivery billing'], [
272
+ 'Server-only STREAM_ACCOUNT_ID and account-scoped STREAM_API_TOKEN with Stream Write permission',
273
+ ], [
274
+ 'Manual Stream activation and live input setup; server management factory with secret WHIP and WHEP endpoints',
275
+ ], [
276
+ 'Creator/input ownership, viewer authorization and signed playback when private, browser media/ICE, reconnect and session cleanup; live behavior unverified',
277
+ ]),
278
+ install: scaffoldStream,
279
+ },
234
280
  queues: {
235
281
  type: 'service',
236
282
  description: 'Queue producer binding, consumer and dead-letter handling',
@@ -265,8 +311,61 @@ export interface LocalDataStore {
265
311
  setup: requirements('Durable multi-step processing', ['Wrangler'], ['Cloudflare Workflows deployment access'], [], ['Workflow Worker/binding and resumable steps'], ['Retry/resume, idempotency, cancellation and failure recovery']),
266
312
  install: scaffoldWorkflows,
267
313
  },
314
+ 'analytics-engine': {
315
+ selection: { requiresAll: ['hono'] },
316
+ type: 'integration',
317
+ description: 'Workers Analytics Engine dataset binding and server event helper',
318
+ targets: ['packages/analytics-engine'],
319
+ runtime: 'worker',
320
+ install: scaffoldAnalyticsEngine,
321
+ configure: ({ options }) => ({
322
+ analytics_engine_datasets: [
323
+ { binding: 'EVENTS', dataset: resourceName(options.name, 'events').replaceAll('-', '_') },
324
+ ],
325
+ }),
326
+ setup: requirements('Custom server-side analytics', ['Wrangler'], ['Cloudflare Analytics Engine access'], [], ['EVENTS dataset binding; define event semantics and privacy policy'], [
327
+ 'Dataset ingestion, sampled query semantics and privacy filtering; not transactional billing state',
328
+ ]),
329
+ },
330
+ images: {
331
+ selection: { requiresAll: ['hono'] },
332
+ type: 'integration',
333
+ description: 'Cloudflare Images binding and private image transform helper',
334
+ targets: ['packages/images'],
335
+ runtime: 'worker',
336
+ install: scaffoldImages,
337
+ configure: () => ({ images: { binding: 'IMAGES' } }),
338
+ setup: requirements('Image optimization', ['Wrangler'], ['Cloudflare Images account eligibility'], [], ['IMAGES binding; authorize source objects and define transform/usage limits'], ['Real transforms, source ownership and cache isolation']),
339
+ },
340
+ realtimekit: {
341
+ registryDependencies: ['workspace', 'typescript', 'eslint', 'cloudflare-api'],
342
+ selection: { requiresAll: ['hono'] },
343
+ type: 'integration',
344
+ description: 'Cloudflare RealtimeKit server meeting and participant-token helpers',
345
+ targets: ['packages/realtimekit'],
346
+ runtime: 'worker',
347
+ install: scaffoldRealtimeKit,
348
+ environment: ['REALTIMEKIT_ACCOUNT_ID', 'REALTIMEKIT_APP_ID', 'REALTIMEKIT_API_TOKEN'],
349
+ setup: requirements('Audio/video conferencing', ['Cloudflare RealtimeKit API or dashboard'], ['Cloudflare RealtimeKit app and scoped Realtime permissions'], ['Server-only account/app ID and API token'], [
350
+ 'Manual app activation and presets; implement authorized token routes and platform client SDK',
351
+ ], ['Meeting isolation, permissions, reconnect and actual device media/teardown']),
352
+ },
353
+ video: {
354
+ registryDependencies: ['workspace', 'typescript', 'eslint', 'cloudflare-api'],
355
+ selection: { requiresAll: ['hono'] },
356
+ type: 'integration',
357
+ description: 'Cloudflare Stream private on-demand direct video upload helper',
358
+ targets: ['packages/video'],
359
+ runtime: 'worker',
360
+ install: scaffoldVideo,
361
+ environment: ['STREAM_ACCOUNT_ID', 'STREAM_API_TOKEN'],
362
+ setup: requirements('Uploaded video processing and delivery', ['Cloudflare Stream API or dashboard'], ['Cloudflare Stream activation and scoped Stream Write access'], ['Server-only Stream account ID and API token'], [
363
+ 'Authorized one-time upload issuance; implement processing checks, signed playback and retention',
364
+ ], ['Creator ownership, upload/processing limits and private playback on selected devices']),
365
+ },
268
366
  openai: {
269
367
  type: 'package',
368
+ runtime: 'server',
270
369
  description: 'Server-side OpenAI SDK factory',
271
370
  targets: ['packages/ai'],
272
371
  selection: { conflicts: ['ai-sdk'] },
@@ -277,6 +376,7 @@ export interface LocalDataStore {
277
376
  },
278
377
  'ai-sdk': {
279
378
  type: 'package',
379
+ runtime: 'server',
280
380
  description: 'Server-side AI SDK and provider exports',
281
381
  targets: ['packages/ai'],
282
382
  selection: { conflicts: ['openai'] },
@@ -298,6 +398,7 @@ export interface LocalDataStore {
298
398
  },
299
399
  resend: {
300
400
  type: 'package',
401
+ runtime: 'server',
301
402
  description: 'Server-side email SDK factory',
302
403
  targets: ['packages/email'],
303
404
  registryDependencies: ['workspace', 'typescript', 'eslint'],
@@ -308,23 +409,49 @@ export interface LocalDataStore {
308
409
  environment: ['RESEND_API_KEY'],
309
410
  },
310
411
  stripe: {
311
- type: 'package',
312
- description: 'Server-side billing SDK factory',
313
- targets: ['packages/billing'],
412
+ type: 'integration',
413
+ description: 'Authenticated Stripe checkout, portal and server entitlement projection',
414
+ targets: ['packages/billing', 'packages/contracts', 'apps/api'],
415
+ selection: { requiresAll: ['hono'], requiresAny: ['better-auth', 'clerk'] },
314
416
  registryDependencies: ['workspace', 'typescript', 'eslint'],
417
+ resolveDependencies: billingDependencies,
418
+ resolveTargets: ({ has }) => [
419
+ 'packages/billing',
420
+ 'packages/contracts',
421
+ 'apps/api',
422
+ ...(has('expo') ? ['apps/mobile'] : []),
423
+ ],
315
424
  setup: requirements('Web payments and subscriptions', ['Stripe integration or CLI'], ['Client-owned Stripe account; test/live access as required'], ['STRIPE_SECRET_KEY; STRIPE_WEBHOOK_SECRET'], ['Products/prices, signed webhooks and entitlement implementation'], ['Test purchase/cancellation, webhook replay and transactional idempotency']),
316
- package: packageSource('billing', "import Stripe from 'stripe';\nexport function createBilling(apiKey: string) { return new Stripe(apiKey); }\n", { stripe: STACK_DEPENDENCIES['stripe'] }),
317
- environment: ['STRIPE_SECRET_KEY', 'STRIPE_WEBHOOK_SECRET'],
425
+ install: scaffoldStripe,
426
+ environment: [...BILLING_ENVIRONMENT_KEYS, 'STRIPE_SECRET_KEY', 'STRIPE_WEBHOOK_SECRET'],
318
427
  },
319
428
  revenuecat: {
320
429
  type: 'integration',
321
- description: 'Cross-store entitlement integration guidance',
322
- targets: ['packages/billing/revenuecat.md'],
323
- selection: { requiresAll: ['stripe'] },
324
- registryDependencies: ['stripe'],
325
- setup: requirements('Cross-store subscription entitlements alongside Stripe', ['RevenueCat integration or API', 'Selected mobile store tooling'], ['RevenueCat project; App Store/Play Store product access'], ['Platform public SDK keys; server API/webhook credentials as required'], ['Integration guidance only; install platform SDKs and configure offerings/store products'], ['Sandbox purchase/restore, verified webhooks and entitlement reconciliation']),
430
+ description: 'Native purchases, restore and server-enforced cross-store entitlements',
431
+ targets: ['packages/billing', 'packages/contracts', 'apps/api'],
432
+ selection: { requiresAll: ['hono'], requiresAny: ['better-auth', 'clerk'] },
433
+ registryDependencies: ['workspace', 'typescript', 'eslint'],
434
+ resolveDependencies: billingDependencies,
435
+ resolveTargets: ({ has }) => [
436
+ 'packages/billing',
437
+ 'packages/contracts',
438
+ 'apps/api',
439
+ ...(has('expo') ? ['apps/mobile'] : []),
440
+ ],
441
+ setup: requirements('Cross-store subscription entitlements; Stripe is optional', ['RevenueCat integration or API', 'Selected mobile store tooling'], ['RevenueCat project; App Store/Play Store product access'], ['Platform public SDK keys; server API/webhook credentials as required'], [
442
+ 'Native purchase SDK and authenticated entitlement APIs; configure offerings/store products before acceptance',
443
+ ], ['Sandbox purchase/restore, verified webhooks and entitlement reconciliation']),
326
444
  install: scaffoldRevenueCat,
327
- environment: ['EXPO_PUBLIC_REVENUECAT_IOS_API_KEY', 'EXPO_PUBLIC_REVENUECAT_ANDROID_API_KEY'],
445
+ environment: [
446
+ ...BILLING_ENVIRONMENT_KEYS,
447
+ 'REVENUECAT_SECRET_KEY',
448
+ 'REVENUECAT_WEBHOOK_AUTHORIZATION',
449
+ 'REVENUECAT_WEBHOOK_SIGNING_SECRET',
450
+ 'REVENUECAT_APP_IDS_JSON',
451
+ 'REVENUECAT_PROJECT_ID',
452
+ 'EXPO_PUBLIC_REVENUECAT_IOS_API_KEY',
453
+ 'EXPO_PUBLIC_REVENUECAT_ANDROID_API_KEY',
454
+ ],
328
455
  },
329
456
  sentry: {
330
457
  type: 'package',
@@ -363,6 +490,7 @@ export async function recordEvents(stream: EventStream, events: Record<string, u
363
490
  },
364
491
  posthog: {
365
492
  type: 'package',
493
+ runtime: 'server',
366
494
  description: 'Server-side product analytics factory',
367
495
  targets: ['packages/analytics'],
368
496
  registryDependencies: ['workspace', 'typescript', 'eslint'],
@@ -412,6 +540,14 @@ const FOUNDATION_ITEMS = defineItems({
412
540
  targets: ['packages/eslint-config'],
413
541
  registryDependencies: ['workspace'],
414
542
  },
543
+ 'cloudflare-api': {
544
+ type: 'foundation',
545
+ installer: 'recipe',
546
+ description: 'Shared server-only Cloudflare media management transport',
547
+ targets: ['packages/cloudflare-api'],
548
+ registryDependencies: ['workspace', 'typescript', 'eslint'],
549
+ install: scaffoldCloudflareTransport,
550
+ },
415
551
  ui: {
416
552
  type: 'foundation',
417
553
  description: 'Shared shadcn/ui, React, Tailwind and Lucide foundation for web apps',
@@ -0,0 +1,15 @@
1
+ export declare const LOCK_FILE = ".anhedral.lock";
2
+ type LockOwner = {
3
+ version: 1;
4
+ pid: number;
5
+ hostname: string;
6
+ token: string;
7
+ createdAt: string;
8
+ };
9
+ type TransactionLock = {
10
+ lockPath: string;
11
+ owner: LockOwner;
12
+ };
13
+ export declare function acquireTransactionLock(root: string): TransactionLock;
14
+ export declare function releaseTransactionLock(lock: TransactionLock): void;
15
+ export {};
@@ -0,0 +1,227 @@
1
+ import { linkSync, lstatSync, readdirSync, rmSync, unlinkSync, writeFileSync } from 'node:fs';
2
+ import { randomUUID } from 'node:crypto';
3
+ import os from 'node:os';
4
+ import path from 'node:path';
5
+ import { readBoundedFile } from './bounded-file.js';
6
+ export const LOCK_FILE = '.anhedral.lock';
7
+ function isRecord(value) {
8
+ return typeof value === 'object' && value !== null && !Array.isArray(value);
9
+ }
10
+ function lstatIfPresent(target) {
11
+ try {
12
+ return lstatSync(target);
13
+ }
14
+ catch (error) {
15
+ if (error.code === 'ENOENT')
16
+ return null;
17
+ throw error;
18
+ }
19
+ }
20
+ function pathEntryExists(target) {
21
+ return lstatIfPresent(target) !== null;
22
+ }
23
+ function parseLockOwner(lockPath) {
24
+ if (lstatSync(lockPath).isSymbolicLink()) {
25
+ throw new Error(`Refusing symbolic-link transaction lock at ${lockPath}.`);
26
+ }
27
+ let value;
28
+ try {
29
+ value = JSON.parse(readBoundedFile(lockPath, 16 * 1024).toString('utf8'));
30
+ }
31
+ catch (error) {
32
+ throw new Error(`Cannot read transaction lock owner at ${lockPath}; remove it only after confirming no Anhedral process is running.`, { cause: error });
33
+ }
34
+ if (!isRecord(value) ||
35
+ value.version !== 1 ||
36
+ !Number.isSafeInteger(value.pid) ||
37
+ value.pid <= 0 ||
38
+ typeof value.hostname !== 'string' ||
39
+ typeof value.token !== 'string' ||
40
+ typeof value.createdAt !== 'string') {
41
+ throw new Error(`Invalid transaction lock owner at ${lockPath}; remove it only after confirming no Anhedral process is running.`);
42
+ }
43
+ return value;
44
+ }
45
+ function readLockOwnerIfPresent(lockPath) {
46
+ try {
47
+ return parseLockOwner(lockPath);
48
+ }
49
+ catch (error) {
50
+ const candidate = error;
51
+ if (candidate.code === 'ENOENT' || candidate.cause?.code === 'ENOENT')
52
+ return null;
53
+ throw error;
54
+ }
55
+ }
56
+ function isProcessAlive(pid) {
57
+ try {
58
+ process.kill(pid, 0);
59
+ return true;
60
+ }
61
+ catch (error) {
62
+ const code = error.code;
63
+ if (code === 'ESRCH')
64
+ return false;
65
+ if (code === 'EPERM')
66
+ return true;
67
+ throw error;
68
+ }
69
+ }
70
+ function cleanupTemporaryLocks(root, owner, temporaryPath) {
71
+ for (const entry of readdirSync(root)) {
72
+ if (!entry.startsWith(`${LOCK_FILE}.`) || !entry.endsWith('.tmp'))
73
+ continue;
74
+ const staleTemporaryPath = path.join(root, entry);
75
+ if (staleTemporaryPath === temporaryPath)
76
+ continue;
77
+ let temporaryOwner;
78
+ try {
79
+ temporaryOwner = parseLockOwner(staleTemporaryPath);
80
+ }
81
+ catch (error) {
82
+ throw new Error(`Cannot safely classify transaction lock artifact at ${staleTemporaryPath}; inspect it manually before retrying.`, { cause: error });
83
+ }
84
+ if (temporaryOwner.hostname !== owner.hostname) {
85
+ throw new Error(`Transaction lock artifact at ${staleTemporaryPath} belongs to another host; inspect it manually before retrying.`);
86
+ }
87
+ if (!isProcessAlive(temporaryOwner.pid)) {
88
+ unlinkSync(staleTemporaryPath);
89
+ }
90
+ }
91
+ }
92
+ function claimReclamation(lockPath, reclaimPath, temporaryPath, owner) {
93
+ try {
94
+ linkSync(temporaryPath, reclaimPath);
95
+ }
96
+ catch (error) {
97
+ if (error.code === 'EEXIST') {
98
+ const reclaimer = readLockOwnerIfPresent(reclaimPath);
99
+ if (!reclaimer) {
100
+ return false;
101
+ }
102
+ if (reclaimer.hostname === owner.hostname && !isProcessAlive(reclaimer.pid)) {
103
+ unlinkSync(reclaimPath);
104
+ return false;
105
+ }
106
+ throw new Error(`A stale Anhedral lock is being recovered (${lockPath}, pid ${reclaimer.pid} on ${reclaimer.hostname}); retry the command.`);
107
+ }
108
+ throw error;
109
+ }
110
+ return true;
111
+ }
112
+ function reclaimTransactionLock(lockPath, reclaimPath, temporaryPath, owner) {
113
+ const existing = readLockOwnerIfPresent(lockPath);
114
+ if (!existing) {
115
+ return 'retry';
116
+ }
117
+ if (existing.hostname !== owner.hostname || isProcessAlive(existing.pid)) {
118
+ throw new Error(`Another Anhedral operation is already running (${lockPath}, pid ${existing.pid} on ${existing.hostname}).`);
119
+ }
120
+ if (!claimReclamation(lockPath, reclaimPath, temporaryPath, owner))
121
+ return 'retry';
122
+ try {
123
+ if (!pathEntryExists(lockPath))
124
+ return 'next';
125
+ const current = parseLockOwner(lockPath);
126
+ if (current.token !== existing.token)
127
+ return 'next';
128
+ if (current.hostname !== owner.hostname || isProcessAlive(current.pid)) {
129
+ throw new Error(`Another Anhedral operation is already running (${lockPath}, pid ${current.pid} on ${current.hostname}).`);
130
+ }
131
+ unlinkSync(lockPath);
132
+ }
133
+ finally {
134
+ if (pathEntryExists(reclaimPath)) {
135
+ const reclaimer = parseLockOwner(reclaimPath);
136
+ if (reclaimer.token === owner.token)
137
+ unlinkSync(reclaimPath);
138
+ }
139
+ }
140
+ return 'next';
141
+ }
142
+ function assertLockRoot(root) {
143
+ const rootStat = lstatIfPresent(root);
144
+ if (!rootStat)
145
+ throw new Error(`Transaction root is not a directory: ${root}`);
146
+ if (rootStat.isSymbolicLink()) {
147
+ throw new Error(`Refusing transaction root that is a symbolic link: ${root}`);
148
+ }
149
+ if (!rootStat.isDirectory())
150
+ throw new Error(`Transaction root is not a directory: ${root}`);
151
+ }
152
+ function clearDeadReclaimer(lockPath, reclaimPath, owner) {
153
+ const activeReclaimer = readLockOwnerIfPresent(reclaimPath);
154
+ if (activeReclaimer) {
155
+ if (activeReclaimer.hostname === owner.hostname && !isProcessAlive(activeReclaimer.pid)) {
156
+ try {
157
+ unlinkSync(reclaimPath);
158
+ }
159
+ catch (error) {
160
+ if (error.code !== 'ENOENT')
161
+ throw error;
162
+ }
163
+ return true;
164
+ }
165
+ throw new Error(`An Anhedral lock is being recovered (${lockPath}, pid ${activeReclaimer.pid} on ${activeReclaimer.hostname}); retry the command.`);
166
+ }
167
+ return false;
168
+ }
169
+ function cleanupAcquiredLock(root, lockPath, owner, temporaryPath) {
170
+ try {
171
+ cleanupTemporaryLocks(root, owner, temporaryPath);
172
+ }
173
+ catch (error) {
174
+ const current = readLockOwnerIfPresent(lockPath);
175
+ if (current?.token === owner.token)
176
+ unlinkSync(lockPath);
177
+ throw error;
178
+ }
179
+ }
180
+ export function acquireTransactionLock(root) {
181
+ assertLockRoot(root);
182
+ const lockPath = path.join(root, LOCK_FILE);
183
+ const reclaimPath = `${lockPath}.reclaim`;
184
+ const owner = {
185
+ version: 1,
186
+ pid: process.pid,
187
+ hostname: os.hostname(),
188
+ token: `${process.pid}-${randomUUID()}`,
189
+ createdAt: new Date().toISOString(),
190
+ };
191
+ const temporaryPath = `${lockPath}.${owner.token}.tmp`;
192
+ writeFileSync(temporaryPath, JSON.stringify(owner) + '\n', {
193
+ encoding: 'utf8',
194
+ flag: 'wx',
195
+ mode: 0o600,
196
+ });
197
+ try {
198
+ for (let attempt = 0; attempt < 3; attempt += 1) {
199
+ if (clearDeadReclaimer(lockPath, reclaimPath, owner)) {
200
+ attempt -= 1;
201
+ continue;
202
+ }
203
+ try {
204
+ linkSync(temporaryPath, lockPath);
205
+ cleanupAcquiredLock(root, lockPath, owner, temporaryPath);
206
+ return { lockPath, owner };
207
+ }
208
+ catch (error) {
209
+ if (error.code !== 'EEXIST')
210
+ throw error;
211
+ }
212
+ if (reclaimTransactionLock(lockPath, reclaimPath, temporaryPath, owner) === 'retry')
213
+ attempt -= 1;
214
+ }
215
+ }
216
+ finally {
217
+ rmSync(temporaryPath, { force: true });
218
+ }
219
+ throw new Error(`Could not acquire Anhedral transaction lock (${lockPath}).`);
220
+ }
221
+ export function releaseTransactionLock(lock) {
222
+ if (!pathEntryExists(lock.lockPath))
223
+ return;
224
+ const current = parseLockOwner(lock.lockPath);
225
+ if (current.token === lock.owner.token)
226
+ unlinkSync(lock.lockPath);
227
+ }