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.
- package/README.md +171 -18
- package/dist/bin.js +48 -493
- package/dist/capabilities.d.ts +3 -3
- package/dist/capability-contract.js +16 -1
- package/dist/cli-arguments.d.ts +8 -0
- package/dist/cli-arguments.js +32 -0
- package/dist/cli-commands.d.ts +3 -0
- package/dist/cli-commands.js +114 -0
- package/dist/cli-delivery.d.ts +3 -0
- package/dist/cli-delivery.js +172 -0
- package/dist/cli-output.js +231 -205
- package/dist/command-schema.js +8 -2
- package/dist/command.js +9 -11
- package/dist/delivery-evidence.d.ts +62 -0
- package/dist/delivery-evidence.js +186 -0
- package/dist/delivery.d.ts +3 -40
- package/dist/delivery.js +7 -182
- package/dist/dependencies.d.ts +7 -1
- package/dist/dependencies.js +15 -1
- package/dist/index.d.ts +1 -0
- package/dist/index.js +1 -0
- package/dist/mobile-delivery.d.ts +21 -44
- package/dist/mobile-delivery.js +127 -80
- package/dist/platforms/mobile.d.ts +1 -1
- package/dist/platforms/mobile.js +44 -3
- package/dist/project-state.js +4 -1
- package/dist/provider-auth.js +9 -3
- package/dist/providers/adapters.js +9 -3
- package/dist/providers/runtime.js +11 -0
- package/dist/readiness.js +4 -2
- package/dist/registry/add.js +40 -7
- package/dist/registry/options.js +12 -0
- package/dist/registry/presets.d.ts +4 -0
- package/dist/registry/presets.js +41 -0
- package/dist/registry/resolve.d.ts +3 -1
- package/dist/registry/resolve.js +40 -14
- package/dist/registry/types.d.ts +1 -0
- package/dist/registry/usage.js +1 -1
- package/dist/runtime-policy.js +4 -1
- package/dist/scaffold/api.js +10 -2
- package/dist/scaffold/auth.d.ts +1 -1
- package/dist/scaffold/auth.js +22 -6
- package/dist/scaffold/backend.d.ts +6 -0
- package/dist/scaffold/backend.js +224 -0
- package/dist/scaffold/billing-config.d.ts +1 -0
- package/dist/scaffold/billing-config.js +73 -0
- package/dist/scaffold/billing-contracts.d.ts +2 -0
- package/dist/scaffold/billing-contracts.js +48 -0
- package/dist/scaffold/billing-providers.d.ts +1 -0
- package/dist/scaffold/billing-providers.js +249 -0
- package/dist/scaffold/billing-schema.d.ts +1 -0
- package/dist/scaffold/billing-schema.js +34 -0
- package/dist/scaffold/billing-security.d.ts +1 -0
- package/dist/scaffold/billing-security.js +46 -0
- package/dist/scaffold/billing-server.d.ts +1 -0
- package/dist/scaffold/billing-server.js +139 -0
- package/dist/scaffold/billing-store.d.ts +1 -0
- package/dist/scaffold/billing-store.js +72 -0
- package/dist/scaffold/billing.d.ts +2 -0
- package/dist/scaffold/billing.js +216 -0
- package/dist/scaffold/cloudflare-services.d.ts +8 -0
- package/dist/scaffold/cloudflare-services.js +198 -0
- package/dist/scaffold/compose.js +2 -0
- package/dist/scaffold/database.js +19 -2
- package/dist/scaffold/documentation.js +11 -6
- package/dist/scaffold/expo-auth.d.ts +3 -0
- package/dist/scaffold/expo-auth.js +192 -0
- package/dist/scaffold/expo-billing.d.ts +3 -0
- package/dist/scaffold/expo-billing.js +292 -0
- package/dist/scaffold/expo-runtime.d.ts +3 -0
- package/dist/scaffold/expo-runtime.js +134 -0
- package/dist/scaffold/integrations.d.ts +2 -1
- package/dist/scaffold/integrations.js +7 -2
- package/dist/scaffold/stream.d.ts +2 -0
- package/dist/scaffold/stream.js +114 -0
- package/dist/scaffold/void.js +13 -5
- package/dist/scaffold/web.js +2 -0
- package/dist/scaffold/workspace.js +6 -1
- package/dist/service-readers.js +1 -1
- package/dist/services-command.js +8 -6
- package/dist/ship.d.ts +15 -15
- package/dist/ship.js +3 -1
- package/dist/stack-registry.d.ts +13 -2
- package/dist/stack-registry.js +152 -16
- package/dist/transaction-lock.d.ts +15 -0
- package/dist/transaction-lock.js +227 -0
- package/dist/transaction.js +2 -208
- package/dist/vercel-project.d.ts +101 -0
- package/dist/vercel-project.js +305 -0
- package/dist/vercel.d.ts +3 -36
- package/dist/vercel.js +3 -300
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/docs/anhedral-stack.md +122 -0
- package/docs/software-factory.md +402 -7
- package/docs/stack-standard.md +226 -49
- package/docs/verification.md +557 -0
- package/package.json +7 -7
- package/docs/cli-design.md +0 -67
- package/docs/plugin-ui.md +0 -102
- package/docs/provider-configuration.md +0 -116
- package/docs/void-verification.md +0 -185
package/dist/stack-registry.js
CHANGED
|
@@ -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
|
|
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('
|
|
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 }) => [
|
|
198
|
-
|
|
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: '
|
|
312
|
-
description: '
|
|
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
|
-
|
|
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: '
|
|
322
|
-
targets: ['packages/billing/
|
|
323
|
-
selection: { requiresAll: ['
|
|
324
|
-
registryDependencies: ['
|
|
325
|
-
|
|
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: [
|
|
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
|
+
}
|