anhedral 0.10.1 → 0.11.1

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 (183) hide show
  1. package/README.md +79 -124
  2. package/assets/patches/LICENSE.braces +21 -0
  3. package/assets/patches/LICENSE.node-forge +50 -0
  4. package/assets/patches/audit-deps.mjs +167 -0
  5. package/assets/patches/braces@3.0.3.patch +127 -0
  6. package/assets/patches/node-forge@1.4.0.patch +41 -0
  7. package/dist/auth-schema.js +3 -3
  8. package/dist/bin.js +284 -163
  9. package/dist/capabilities.d.ts +4 -4
  10. package/dist/capabilities.js +6 -2
  11. package/dist/capability-contract.d.ts +47 -0
  12. package/dist/capability-contract.js +153 -0
  13. package/dist/catalog-model.d.ts +24 -0
  14. package/dist/catalog-model.js +1 -0
  15. package/dist/catalog-registration.d.ts +16 -0
  16. package/dist/catalog-registration.js +22 -0
  17. package/dist/catalog-snapshot.d.ts +5 -0
  18. package/dist/catalog-snapshot.js +97 -0
  19. package/dist/cli-arguments.d.ts +16 -0
  20. package/dist/cli-arguments.js +115 -0
  21. package/dist/cli-output.d.ts +8 -0
  22. package/dist/cli-output.js +236 -0
  23. package/dist/cloudflare.d.ts +14 -3
  24. package/dist/cloudflare.js +196 -36
  25. package/dist/command-schema.d.ts +21 -0
  26. package/dist/command-schema.js +418 -0
  27. package/dist/delivery.d.ts +12 -5
  28. package/dist/delivery.js +173 -39
  29. package/dist/dependencies.d.ts +24 -0
  30. package/dist/dependencies.js +48 -0
  31. package/dist/dependency-patches.d.ts +7 -0
  32. package/dist/dependency-patches.js +125 -0
  33. package/dist/index.d.ts +26 -1
  34. package/dist/index.js +17 -1
  35. package/dist/inspector-model.d.ts +123 -0
  36. package/dist/inspector-model.js +1 -0
  37. package/dist/integration-service-readers.d.ts +13 -0
  38. package/dist/integration-service-readers.js +173 -0
  39. package/dist/lifecycle-model.d.ts +15 -0
  40. package/dist/lifecycle-model.js +20 -0
  41. package/dist/lifecycle.d.ts +11 -0
  42. package/dist/lifecycle.js +91 -0
  43. package/dist/mobile-delivery.d.ts +100 -0
  44. package/dist/mobile-delivery.js +319 -0
  45. package/dist/neon-service-data.d.ts +8 -0
  46. package/dist/neon-service-data.js +117 -0
  47. package/dist/platforms/mobile.js +8 -5
  48. package/dist/pnpm-policy.d.ts +2 -2
  49. package/dist/pnpm-policy.js +19 -45
  50. package/dist/project-catalog.d.ts +41 -0
  51. package/dist/project-catalog.js +288 -0
  52. package/dist/project-config.d.ts +14 -0
  53. package/dist/project-config.js +89 -0
  54. package/dist/project-inspector.d.ts +4 -0
  55. package/dist/project-inspector.js +702 -0
  56. package/dist/project-lifecycle.d.ts +25 -0
  57. package/dist/project-lifecycle.js +57 -0
  58. package/dist/project-state.d.ts +22 -1
  59. package/dist/project-state.js +361 -27
  60. package/dist/provider-auth.d.ts +41 -0
  61. package/dist/provider-auth.js +209 -0
  62. package/dist/provider-readiness.js +27 -10
  63. package/dist/providers/adapters.d.ts +17 -0
  64. package/dist/providers/adapters.js +272 -0
  65. package/dist/providers/api.d.ts +29 -0
  66. package/dist/providers/api.js +253 -0
  67. package/dist/providers/config.d.ts +15 -0
  68. package/dist/providers/config.js +182 -0
  69. package/dist/providers/definitions.d.ts +318 -0
  70. package/dist/providers/definitions.js +127 -0
  71. package/dist/providers/provision.d.ts +24 -0
  72. package/dist/providers/provision.js +76 -0
  73. package/dist/providers/receipts.d.ts +20 -0
  74. package/dist/providers/receipts.js +66 -0
  75. package/dist/providers/recovery-verification.d.ts +7 -0
  76. package/dist/providers/recovery-verification.js +112 -0
  77. package/dist/providers/recovery.d.ts +30 -0
  78. package/dist/providers/recovery.js +34 -0
  79. package/dist/providers/runtime.d.ts +10 -0
  80. package/dist/providers/runtime.js +254 -0
  81. package/dist/providers/schema.d.ts +28 -0
  82. package/dist/providers/schema.js +49 -0
  83. package/dist/providers/state.d.ts +55 -0
  84. package/dist/providers/state.js +289 -0
  85. package/dist/provision.d.ts +10 -1
  86. package/dist/provision.js +91 -4
  87. package/dist/r2-service-data.d.ts +2 -0
  88. package/dist/r2-service-data.js +136 -0
  89. package/dist/readiness.js +9 -13
  90. package/dist/registry/add.d.ts +6 -0
  91. package/dist/registry/add.js +93 -22
  92. package/dist/registry/commands.d.ts +3 -2
  93. package/dist/registry/commands.js +52 -15
  94. package/dist/registry/options.d.ts +1 -1
  95. package/dist/registry/options.js +5 -4
  96. package/dist/registry/preview.d.ts +11 -0
  97. package/dist/registry/preview.js +91 -0
  98. package/dist/registry/receipt.d.ts +1 -0
  99. package/dist/registry/receipt.js +19 -4
  100. package/dist/registry/resolve.js +5 -1
  101. package/dist/registry/usage.d.ts +10 -0
  102. package/dist/registry/usage.js +18 -37
  103. package/dist/render.d.ts +2 -0
  104. package/dist/render.js +6 -0
  105. package/dist/runtime-policy.d.ts +4 -0
  106. package/dist/runtime-policy.js +21 -0
  107. package/dist/scaffold/auth.js +3 -19
  108. package/dist/scaffold/bootstrap.js +2 -2
  109. package/dist/scaffold/compose.js +9 -3
  110. package/dist/scaffold/database.js +107 -25
  111. package/dist/scaffold/documentation.js +18 -13
  112. package/dist/scaffold/lint.d.ts +4 -0
  113. package/dist/scaffold/lint.js +56 -0
  114. package/dist/scaffold/neon-realtime.d.ts +2 -0
  115. package/dist/scaffold/neon-realtime.js +97 -0
  116. package/dist/scaffold/stack-documentation.js +1 -1
  117. package/dist/scaffold/void.d.ts +4 -0
  118. package/dist/scaffold/void.js +256 -0
  119. package/dist/scaffold/web.js +7 -1
  120. package/dist/scaffold/workspace.js +127 -25
  121. package/dist/service-deletion.d.ts +29 -0
  122. package/dist/service-deletion.js +195 -0
  123. package/dist/service-descriptor.d.ts +10 -0
  124. package/dist/service-descriptor.js +78 -0
  125. package/dist/service-model.d.ts +49 -0
  126. package/dist/service-model.js +8 -0
  127. package/dist/service-operations.d.ts +29 -0
  128. package/dist/service-operations.js +78 -0
  129. package/dist/service-readers.d.ts +8 -0
  130. package/dist/service-readers.js +247 -0
  131. package/dist/services-command.d.ts +39 -0
  132. package/dist/services-command.js +100 -0
  133. package/dist/ship.d.ts +348 -0
  134. package/dist/ship.js +237 -0
  135. package/dist/stack-registry.d.ts +4 -2
  136. package/dist/stack-registry.js +48 -12
  137. package/dist/standard.d.ts +2 -1
  138. package/dist/standard.js +33 -14
  139. package/dist/transaction.d.ts +2 -0
  140. package/dist/transaction.js +10 -0
  141. package/dist/util.js +17 -2
  142. package/dist/vercel.d.ts +5 -3
  143. package/dist/vercel.js +96 -14
  144. package/dist/version.d.ts +1 -1
  145. package/dist/version.js +1 -1
  146. package/dist/vinext.d.ts +1 -0
  147. package/dist/vinext.js +13 -1
  148. package/dist/void-execution.d.ts +10 -0
  149. package/dist/void-execution.js +94 -0
  150. package/dist/void-migrations.d.ts +6 -0
  151. package/dist/void-migrations.js +110 -0
  152. package/dist/void-state.d.ts +16 -0
  153. package/dist/void-state.js +65 -0
  154. package/dist/void.d.ts +3 -0
  155. package/dist/void.js +5 -0
  156. package/docs/cli-design.md +67 -0
  157. package/docs/delivery-workflow.md +32 -17
  158. package/docs/plugin-ui.md +102 -0
  159. package/docs/provider-configuration.md +116 -0
  160. package/docs/stack-standard.md +175 -0
  161. package/docs/void-verification.md +185 -0
  162. package/package.json +29 -23
  163. package/assets/anhedral-cli-init-technical.svg +0 -322
  164. package/assets/anhedral-cli-init.svg +0 -322
  165. package/assets/anhedral-mark.svg +0 -4
  166. package/assets/anhedral.svg +0 -4
  167. package/assets/favicon.ico +0 -0
  168. package/assets/security/LICENSES.txt +0 -63
  169. package/assets/security/audit-deps.mjs +0 -300
  170. package/assets/security/braces-regression.mjs +0 -102
  171. package/assets/security/braces@3.0.3.patch +0 -285
  172. package/assets/security/decode-uri-component@0.2.2.patch +0 -149
  173. package/assets/security/decoder-regression.mjs +0 -37
  174. package/assets/security/forge-regression.mjs +0 -46
  175. package/assets/security/manifest.json +0 -53
  176. package/assets/security/node-forge@1.4.0.patch +0 -26
  177. package/dist/managed-hosting.d.ts +0 -49
  178. package/dist/managed-hosting.js +0 -373
  179. package/dist/security-backports.d.ts +0 -3
  180. package/dist/security-backports.js +0 -26
  181. package/docs/application-stack-standard.md +0 -104
  182. package/docs/managed-hosting-architecture.md +0 -87
  183. package/docs/sponsorships.md +0 -25
@@ -0,0 +1,94 @@
1
+ import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'node:fs';
2
+ import path from 'node:path';
3
+ import {} from './project-state.js';
4
+ import { prepareVoidMigrations } from './void-migrations.js';
5
+ import { VOID_VERSION, supportsVoidRuntime } from './void.js';
6
+ /** Validate the local pin: never download or execute an unpinned fallback during delivery. */
7
+ async function assertVoidInstallation(directory, run, env) {
8
+ const version = (await run('node', ['-p', 'process.versions.node'], directory, env)).trim();
9
+ if (!supportsVoidRuntime(version))
10
+ throw new Error('Void delivery requires Node >=24.21.0.');
11
+ const pkg = JSON.parse(readFileSync(path.join(directory, 'package.json'), 'utf8'));
12
+ if ((pkg.dependencies?.void ?? pkg.devDependencies?.void) !== VOID_VERSION)
13
+ throw new Error(`Void delivery requires the exact local void@${VOID_VERSION} dependency.`);
14
+ const installed = (await run('pnpm', ['exec', 'void', '--version'], directory, env)).trim();
15
+ if (installed !== VOID_VERSION)
16
+ throw new Error(`Installed Void version differs from required ${VOID_VERSION}.`);
17
+ }
18
+ /** Bridge the already verified Wrangler identity into Void's separate cf process. */
19
+ export async function voidCloudflareEnvironment(directory, run, env) {
20
+ if (env.CLOUDFLARE_API_TOKEN)
21
+ return env;
22
+ let credentials;
23
+ try {
24
+ const raw = await run('pnpm', ['exec', 'wrangler', 'auth', 'token', '--json'], directory, env);
25
+ if (Buffer.byteLength(raw) > 64 * 1024)
26
+ throw new Error();
27
+ credentials = JSON.parse(raw);
28
+ }
29
+ catch {
30
+ throw new Error('Cannot retrieve structured Cloudflare credentials for Void delivery.');
31
+ }
32
+ if (!credentials || typeof credentials !== 'object' || Array.isArray(credentials))
33
+ throw new Error('Void requires scoped Cloudflare API-token or OAuth access.');
34
+ const credential = credentials;
35
+ if (!['oauth', 'api_token'].includes(String(credential.type)) ||
36
+ typeof credential.token !== 'string' ||
37
+ !/^[\x21-\x7e]{1,16384}$/.test(credential.token))
38
+ throw new Error('Void requires scoped Cloudflare API-token or OAuth access.');
39
+ return { ...env, CLOUDFLARE_API_TOKEN: credential.token };
40
+ }
41
+ /** Pin direct Cloudflare operations before secrets on a fresh checkout. */
42
+ function selectVoidCloudflare(directory) {
43
+ const folder = path.join(directory, '.void');
44
+ const file = path.join(folder, 'project.json');
45
+ if (existsSync(file)) {
46
+ const selection = JSON.parse(readFileSync(file, 'utf8'));
47
+ if (selection.platform !== 'cloudflare')
48
+ throw new Error('Void operation target must explicitly select the customer Cloudflare account.');
49
+ return;
50
+ }
51
+ mkdirSync(folder, { recursive: true, mode: 0o700 });
52
+ writeFileSync(file, JSON.stringify({ platform: 'cloudflare' }) + '\n', {
53
+ mode: 0o600,
54
+ flag: 'wx',
55
+ });
56
+ }
57
+ export function voidServerSecrets(values) {
58
+ return Object.fromEntries(Object.entries(values).filter(([key]) => !['VITE_', 'NEXT_PUBLIC_', 'EXPO_PUBLIC_'].some((prefix) => key.startsWith(prefix))));
59
+ }
60
+ /** Secret put is noninteractive with stdin; sync prompts even in CI in void@0.27. */
61
+ export async function syncVoidSecrets(directory, values, run, env, beforeMutation) {
62
+ for (const [key, value] of Object.entries(values)) {
63
+ if (!/^[A-Z][A-Z0-9_]*$/.test(key) ||
64
+ ['VITE_', 'NEXT_PUBLIC_', 'EXPO_PUBLIC_'].some((prefix) => key.startsWith(prefix)))
65
+ throw new Error('Void production secrets must be declared server environment keys.');
66
+ if (typeof value !== 'string' || !value.length || value.includes('\0') || value.endsWith('\n'))
67
+ throw new Error('Void secret values must be nonempty strings without NUL bytes or terminal newlines.');
68
+ }
69
+ if (!Object.keys(values).length)
70
+ return;
71
+ selectVoidCloudflare(directory);
72
+ await assertVoidInstallation(directory, run, env);
73
+ const authenticated = await voidCloudflareEnvironment(directory, run, env);
74
+ for (const [key, value] of Object.entries(values)) {
75
+ selectVoidCloudflare(directory);
76
+ await beforeMutation?.();
77
+ await run('pnpm', ['exec', 'void', 'secret', 'put', key], directory, authenticated, value);
78
+ }
79
+ }
80
+ export async function deployVoidTarget(directory, run, env) {
81
+ await assertVoidInstallation(directory, run, env);
82
+ if (existsSync(path.join(directory, 'anhedral.cloudflare.json')))
83
+ prepareVoidMigrations(path.resolve(directory, '../..'), directory, JSON.parse(readFileSync(path.join(directory, 'anhedral.cloudflare.json'), 'utf8')));
84
+ const authenticated = await voidCloudflareEnvironment(directory, run, env);
85
+ return run('pnpm', ['exec', 'void', 'deploy', '--platform', 'cloudflare'], directory, authenticated);
86
+ }
87
+ export async function rollbackVoidTarget(directory, versionId, run, env) {
88
+ if (!/^[a-f0-9-]{36}$/i.test(versionId))
89
+ throw new Error('Void rollback requires a complete Worker Version ID.');
90
+ selectVoidCloudflare(directory);
91
+ await assertVoidInstallation(directory, run, env);
92
+ const authenticated = await voidCloudflareEnvironment(directory, run, env);
93
+ return run('pnpm', ['exec', 'void', 'project', 'rollback', versionId], directory, authenticated);
94
+ }
@@ -0,0 +1,6 @@
1
+ /**
2
+ * Void 0.27 validates conventional app db/migrations even when Wrangler applies
3
+ * a custom directory. Mirror only the designated owner's reviewed SQL/metadata,
4
+ * then let Void compare that validated set against packages/db/drizzle.
5
+ */
6
+ export declare function prepareVoidMigrations(root: string, directory: string, config: Record<string, unknown>): void;
@@ -0,0 +1,110 @@
1
+ import { createHash } from 'node:crypto';
2
+ import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, writeFileSync, } from 'node:fs';
3
+ import path from 'node:path';
4
+ const digest = (value) => createHash('sha256').update(value).digest('hex');
5
+ function files(directory, prefix = '') {
6
+ if (!existsSync(directory))
7
+ return [];
8
+ const result = [];
9
+ for (const name of readdirSync(directory)) {
10
+ const file = path.join(directory, name);
11
+ if (lstatSync(file).isSymbolicLink())
12
+ throw new Error('Void migration sources and generated files must not contain symlinks.');
13
+ if (lstatSync(file).isDirectory())
14
+ result.push(...files(file, prefix + name + '/'));
15
+ else if (lstatSync(file).isFile())
16
+ result.push(prefix + name);
17
+ else
18
+ throw new Error('Void migration sources must contain regular files.');
19
+ }
20
+ return result.sort();
21
+ }
22
+ function assertSafeAncestors(root, directory) {
23
+ const relative = path.relative(root, directory);
24
+ if (relative.startsWith('..') || path.isAbsolute(relative))
25
+ throw new Error('Void migration preparation must stay inside the application workspace.');
26
+ let current = root;
27
+ for (const component of relative.split(path.sep)) {
28
+ current = path.join(current, component);
29
+ if (existsSync(current) && lstatSync(current).isSymbolicLink())
30
+ throw new Error('Void migration paths must not traverse symlinks.');
31
+ }
32
+ }
33
+ /**
34
+ * Void 0.27 validates conventional app db/migrations even when Wrangler applies
35
+ * a custom directory. Mirror only the designated owner's reviewed SQL/metadata,
36
+ * then let Void compare that validated set against packages/db/drizzle.
37
+ */
38
+ export function prepareVoidMigrations(root, directory, config) {
39
+ const requestedRoot = path.resolve(root);
40
+ root = realpathSync(root);
41
+ const requestedDirectory = path.resolve(directory);
42
+ const requestedRelative = path.relative(requestedRoot, requestedDirectory);
43
+ if (!requestedRelative.startsWith('..') && !path.isAbsolute(requestedRelative))
44
+ assertSafeAncestors(requestedRoot, requestedDirectory);
45
+ // Normalize macOS temporary-directory aliases before workspace comparisons.
46
+ if (lstatSync(requestedDirectory).isSymbolicLink())
47
+ throw new Error('Void migration paths must not traverse symlinks.');
48
+ const realDirectory = realpathSync(requestedDirectory);
49
+ const relativeDirectory = path.relative(root, realDirectory);
50
+ if (relativeDirectory.startsWith('..') || path.isAbsolute(relativeDirectory))
51
+ throw new Error('Void migration preparation must stay inside the application workspace.');
52
+ directory = realDirectory;
53
+ assertSafeAncestors(root, directory);
54
+ const target = path.join(directory, 'db/migrations');
55
+ const receiptFile = path.join(directory, '.void/anhedral-migrations.json');
56
+ assertSafeAncestors(root, target);
57
+ assertSafeAncestors(root, receiptFile);
58
+ const databases = Array.isArray(config.d1_databases) ? config.d1_databases : [];
59
+ const owners = databases.filter((entry) => typeof entry.migrations_dir === 'string');
60
+ if (owners.length > 1)
61
+ throw new Error('One Void target may own only one shared D1 migration set.');
62
+ let receipt = null;
63
+ if (existsSync(receiptFile)) {
64
+ const parsed = JSON.parse(readFileSync(receiptFile, 'utf8'));
65
+ if (parsed.schemaVersion !== 1 ||
66
+ !parsed.files ||
67
+ typeof parsed.files !== 'object' ||
68
+ Array.isArray(parsed.files))
69
+ throw new Error('Invalid Void migration ownership receipt.');
70
+ receipt = parsed.files;
71
+ }
72
+ const current = files(target);
73
+ if (existsSync(target) && !receipt)
74
+ throw new Error('Refusing to overwrite an existing app db/migrations directory without Anhedral ownership evidence.');
75
+ if (receipt) {
76
+ const expected = Object.keys(receipt).sort();
77
+ if (JSON.stringify(current) !== JSON.stringify(expected) ||
78
+ current.some((file) => digest(readFileSync(path.join(target, file))) !== receipt[file]))
79
+ throw new Error('Generated Void migrations were edited; review them before preparing deployment.');
80
+ }
81
+ if (!owners.length) {
82
+ if (receipt) {
83
+ rmSync(target, { recursive: true, force: true });
84
+ rmSync(receiptFile);
85
+ }
86
+ return;
87
+ }
88
+ const source = path.resolve(directory, owners[0].migrations_dir);
89
+ const expectedSource = path.join(root, 'packages/db/drizzle');
90
+ if (source !== expectedSource)
91
+ throw new Error('Void migration owner must use packages/db/drizzle.');
92
+ assertSafeAncestors(root, source);
93
+ if (!existsSync(source))
94
+ throw new Error('Shared D1 migration directory does not exist.');
95
+ const names = files(source).filter((file) => /^[^/]+\.sql$/.test(file) || /^meta\/[^/]+\.json$/.test(file));
96
+ if (names.includes('seed.sql'))
97
+ throw new Error('Keep seed.sql outside the deployable shared migration directory.');
98
+ const contents = new Map(names.map((name) => [name, readFileSync(path.join(source, name))]));
99
+ if (receipt)
100
+ rmSync(target, { recursive: true, force: true });
101
+ mkdirSync(target, { recursive: true });
102
+ const hashes = {};
103
+ for (const [name, content] of contents) {
104
+ mkdirSync(path.dirname(path.join(target, name)), { recursive: true });
105
+ writeFileSync(path.join(target, name), content);
106
+ hashes[name] = digest(content);
107
+ }
108
+ mkdirSync(path.dirname(receiptFile), { recursive: true });
109
+ writeFileSync(receiptFile, JSON.stringify({ schemaVersion: 1, files: hashes }, null, 2) + '\n');
110
+ }
@@ -0,0 +1,16 @@
1
+ import type { DeploymentTarget } from './project-state.js';
2
+ export declare function voidLogSnapshot(directory?: string): Set<string>;
3
+ /** Pinned void@0.27.0 JSONL contract, inspected from its published distribution.
4
+ * Log prose never establishes success; exact terminal records and provider state do. */
5
+ export declare function readVoidDeploymentReceipt(before: Set<string>, directory: string, target: DeploymentTarget, startedAt: number, logs?: string): {
6
+ target: string;
7
+ versionId: string;
8
+ urls: string[];
9
+ providerConfirmed: boolean;
10
+ };
11
+ export declare function parseVoidDeploymentLog(source: string, directory: string, target: DeploymentTarget, startedAt: number): {
12
+ target: string;
13
+ versionId: string;
14
+ urls: string[];
15
+ providerConfirmed: boolean;
16
+ } | undefined;
@@ -0,0 +1,65 @@
1
+ import { existsSync, readdirSync, readFileSync, lstatSync, realpathSync } from 'node:fs';
2
+ import { homedir } from 'node:os';
3
+ import path from 'node:path';
4
+ const logsDirectory = () => path.join(homedir(), '.void', 'logs');
5
+ export function voidLogSnapshot(directory = logsDirectory()) {
6
+ return new Set(existsSync(directory)
7
+ ? readdirSync(directory).filter((name) => /^deploy-.+\.jsonl$/.test(name))
8
+ : []);
9
+ }
10
+ /** Pinned void@0.27.0 JSONL contract, inspected from its published distribution.
11
+ * Log prose never establishes success; exact terminal records and provider state do. */
12
+ export function readVoidDeploymentReceipt(before, directory, target, startedAt, logs = logsDirectory()) {
13
+ const receipts = [];
14
+ for (const name of voidLogSnapshot(logs)) {
15
+ if (before.has(name))
16
+ continue;
17
+ const file = path.join(logs, name);
18
+ const stat = lstatSync(file);
19
+ if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 8 * 1024 * 1024)
20
+ continue;
21
+ const receipt = parseVoidDeploymentLog(readFileSync(file, 'utf8'), realpathSync(directory), target, startedAt);
22
+ if (!receipt)
23
+ continue;
24
+ receipts.push(receipt);
25
+ }
26
+ if (receipts.length !== 1)
27
+ throw new Error('No unique successful pinned Void deployment receipt. Deployment may have occurred; inspect provider status before retrying.');
28
+ return receipts[0];
29
+ }
30
+ export function parseVoidDeploymentLog(source, directory, target, startedAt) {
31
+ let records;
32
+ try {
33
+ records = source
34
+ .trim()
35
+ .split('\n')
36
+ .map((line) => JSON.parse(line));
37
+ }
38
+ catch {
39
+ return undefined;
40
+ }
41
+ if (records.some((record) => !record || typeof record !== 'object' || Array.isArray(record)))
42
+ return undefined;
43
+ const start = records[0];
44
+ const end = records.at(-1);
45
+ if (start?.msg !== 'deploy_start' ||
46
+ start.cwd !== directory ||
47
+ typeof start.ts !== 'number' ||
48
+ start.ts < startedAt ||
49
+ end?.msg !== 'deploy_end' ||
50
+ end.ok !== true)
51
+ return undefined;
52
+ const matches = records.filter((record) => record.msg === 'cloudflare_deploy_end' &&
53
+ record.ok === true &&
54
+ record.worker === target.workerName);
55
+ if (matches.length !== 1 ||
56
+ typeof matches[0].versionId !== 'string' ||
57
+ !/^[a-f0-9-]{36}$/i.test(matches[0].versionId))
58
+ return undefined;
59
+ return {
60
+ target: target.id,
61
+ versionId: matches[0].versionId,
62
+ urls: [],
63
+ providerConfirmed: false,
64
+ };
65
+ }
package/dist/void.d.ts ADDED
@@ -0,0 +1,3 @@
1
+ export declare const VOID_VERSION = "0.27.0";
2
+ export declare const VOID_NODE_ENGINE = ">=24.21.0";
3
+ export { supportsVoidRuntime } from './runtime-policy.js';
package/dist/void.js ADDED
@@ -0,0 +1,5 @@
1
+ // Exact delivery pin. Runtime and receipt adapters target this distribution.
2
+ // renovate: datasource=npm depName=void
3
+ export const VOID_VERSION = '0.27.0';
4
+ export const VOID_NODE_ENGINE = '>=24.21.0';
5
+ export { supportsVoidRuntime } from './runtime-policy.js';
@@ -0,0 +1,67 @@
1
+ # CLI behavior and design
2
+
3
+ Anhedral uses three primary commands: `init` scaffolds source, `auth` checks or guides provider authentication, and `ship` provisions/configures the supported stack and coordinates delivery. `add`, `registry`, and `doctor` support development. Hosting selection and advanced release operations remain available through focused command help.
4
+
5
+ The comparison below uses current upstream documentation and source inspected on October 12, 2026. These projects solve different problems; the useful comparison is how they make commands discoverable, changes reviewable, and failures understandable.
6
+
7
+ | Reference | Useful practice | Anhedral behavior |
8
+ | --- | --- | --- |
9
+ | [shadcn CLI](https://ui.shadcn.com/docs/cli) and its [command source](https://github.com/shadcn-ui/ui/tree/main/packages/shadcn/src/commands) | Source ownership, command-specific help, working-directory selection, and previews before changing files | Bundled recipes scaffold owned source; focused help, `--cwd`, and `add --dry-run`, `--diff`, and `--view` support review |
10
+ | [shadcn monorepos](https://ui.shadcn.com/docs/monorepo) | Resolve application and shared-package destinations coherently | The registry resolves dependencies and workspace references into `apps/*` and `packages/*`; additions preserve edited source and record provenance |
11
+ | [GitHub CLI help](https://cli.github.com/manual/gh_help) | Discover commands through focused help topics | `anhedral help <command>` and `<command> --help` show the same options, examples, and relevant prerequisites |
12
+ | [uv command reference](https://docs.astral.sh/uv/reference/cli/) | Consistent output controls and discoverable options | `--quiet` suppresses human output; `--json` retains one machine-readable result; errors remain on stderr |
13
+ | [CLI Guidelines](https://clig.dev/) | Explain outcomes, suggest corrections, and show the next action | Human summaries describe selected parts, pending setup, release evidence, and next steps; command/flag typos receive bounded suggestions |
14
+
15
+ Shadcn's entry point uses Commander and registers separate commands; its initialization separates preflight checks, configuration, templates, registry work, and source updates. Anhedral separates its command metadata, argument handling, human output, registry resolution, staged transactions, and provider operations. The existing provider verification and mutation boundaries remain in the operation modules. See [shadcn's entry point](https://github.com/shadcn-ui/ui/blob/main/packages/shadcn/src/index.ts) and [initialization implementation](https://github.com/shadcn-ui/ui/blob/main/packages/shadcn/src/commands/init.ts).
16
+
17
+ ## Command definitions
18
+
19
+ `src/command-schema.ts` declares command descriptions, option flags and aliases, required or optional values, and repeatable options. Command help and argument validation consume this same metadata; help text is never parsed to infer flag behavior. Singleton command options reject duplicates, required values reject missing input, and boolean options reject inline values without echoing those values. `--allow-email` remains repeatable; `add --diff` and `--view` accept an optional path. Command dispatch and domain-specific value validation remain in the operation handlers.
20
+
21
+ ## Daily use
22
+
23
+ ```sh
24
+ anhedral init client-app --hono --neon --dry-run
25
+ anhedral init client-app --hono --neon
26
+ anhedral auth --cwd client-app
27
+ anhedral ship --cwd client-app --dry-run
28
+
29
+ anhedral add resend --cwd client-app --dry-run
30
+ anhedral add resend --cwd client-app --diff
31
+ anhedral add resend --cwd client-app --view packages/email/src/index.ts
32
+ anhedral add resend --cwd client-app
33
+
34
+ anhedral help ship
35
+ anhedral registry view neon
36
+ anhedral doctor --cwd client-app --json
37
+ ```
38
+
39
+ Complete the selected provider settings and connect the intended hosting account before delivery, as described in [provider configuration](provider-configuration.md). The commands above are examples, not authorization to deploy an application.
40
+
41
+ `--cwd` / `-c` selects the working directory and resolves relative directory arguments from it. `init [directory]` scaffolds a workspace; `add <items...>` adds bundled parts to the current project. Use `anhedral --cwd <directory> add <items...>` to select a project explicitly.
42
+
43
+ ## Output contract
44
+
45
+ - Human output summarizes the operation and relevant next steps. Interactive scaffolding reports its current stage on stderr. Redirected output has no animated terminal effects or progress messages.
46
+ - `--json` emits a complete result on stdout. Failures emit a JSON error, code, and next action on stderr with a nonzero exit status. Login prompts and scaffolding tool output are suppressed in machine mode.
47
+ - `--quiet` / `-q` suppresses human results and progress, retaining errors. Combining it with `--json` retains the JSON result.
48
+ - `--verbose` exposes local scaffolding tool output in human mode. Machine and quiet modes keep tool output suppressed.
49
+ - Help and version checks do not require an existing project or a usable working directory. Unknown commands and flags fail before setup or provider operations; suggestions do not execute corrections.
50
+
51
+ ## Source previews
52
+
53
+ `add --diff [path]` shows an applicable unified patch. `add --view [path]` shows generated source. Both imply a dry run and use the existing staged transaction; neither installs the preview. Without a path, they show the changed generated files. Conflict reporting still applies; previewing a conflict does not permit overwriting edited source.
54
+
55
+ Previews exclude private environment files and `.anhedral/` state. Public `env.example` (Void), `.env.example`, and `.dev.vars.example` templates can be inspected. Binary, nonregular, or files over 256 KiB are marked unavailable. The combined preview has a 1 MiB limit; select a file for larger additions. Diffs use a linear single-contextual-hunk implementation, including explicit handling of final newlines and new empty files.
56
+
57
+ A selection that needs a new upstream web bootstrap cannot produce source previews offline. The CLI explains this and directs the user to the selection-only `--dry-run` plan, which marks `filesChecked: false`. It does not fabricate files or run a networked generator during that preview.
58
+
59
+ ## Deliberate boundaries
60
+
61
+ The public CLI accepts only bundled registry options. It does not accept external URLs, local third-party registries, or arbitrary remote content. It does not force overwrites, infer paid activation, or claim that scaffolding and authentication establish complete product behavior. Provider enrollment, permissions, DNS, billing eligibility, signing, and feature development remain explicit where required.
62
+
63
+ Contract and local-flow tests establish command behavior, source preservation, machine output, and provider request/response handling. Live account provisioning and deployment require separate authorized verification. Release remains a separate review decision.
64
+
65
+ ## Read-only project inspection
66
+
67
+ `anhedral inspect [directory] --json` returns the shared versioned project-inspector contract used by the optional plugin UI. It reads bounded allowlisted local source and receipt files only, with independent errors for unavailable evidence. It does not contact providers, inspect credential values, migrate state or change files. It preserves per-target latest attempt and last successful release as separate facts. Authentication, permission and live provider health remain explicitly unknown. Read time does not make an old receipt fresh.
@@ -1,16 +1,24 @@
1
1
  # Build and deliver an application
2
2
 
3
- Codex implements the product; the CLI supplies scaffolding, selected resource reconciliation and source/provider evidence. Customer-account delivery exists. Managed hosting has a local client foundation, not an operated service. Start with users, flows, audience, budget and observable acceptance criteria; preserve suitable existing apps.
3
+ The CLI supplies the source foundation, provider access checks and supported delivery operations. Feature design, product implementation, custom integrations and ongoing maintenance are development work. Anhedral offers these services; scaffolding and successful deployment do not establish a finished product.
4
+
5
+ Codex implements the product; the CLI supplies scaffolding, selected resource reconciliation and source/provider evidence. Delivery uses your own Cloudflare or Vercel account. Start with users, flows, audience, budget and observable acceptance criteria; preserve suitable existing apps.
4
6
 
5
7
  ## Plan and implement
6
8
 
7
- 1. Choose only needed components from the [stack standard](application-stack-standard.md). Record decisions, ownership, environment/cost assumptions and actual connections in the application's `docs/architecture.md`.
9
+ 1. Choose only needed components from the [stack standard](https://github.com/anhedral/anhedral-cli/blob/main/docs/stack-standard.md). Record decisions, ownership, environment/cost assumptions and actual connections in the application's `docs/architecture.md`.
8
10
  2. Match installed plugin, registry `cliVersion` and executable versions. Check Node/pnpm, Git identity, toolchains and customer provider access. For unpublished development use `pnpm build` and `node dist/bin.js`; never silently substitute `@latest`.
9
- 3. Inspect `new <unused-directory> <flags> --dry-run --json`, then generate with those choices. Review README, AGENTS, setup manifests and resolved lockfile. For initialized apps, preview `add <directory> <items...> --dry-run --json`; additions protect edited source and record registry provenance. Select only items from the bundled Anhedral catalog. If a web addition reports `filesChecked: false`, the preview covers selection and targets only; the actual transaction checks generated-file conflicts before committing. Older projects and runtime relocation require explicit migration. `doctor --providers --json` checks access without configuring infrastructure or certifying production.
11
+ 3. Inspect `init <unused-directory> <flags> --dry-run --json`, then generate with those choices. Review README, AGENTS, setup manifests and resolved lockfile. For initialized apps, preview `anhedral --cwd <directory> add <items...> --dry-run --json`; additions protect edited source and record registry provenance. Select only items from the bundled Anhedral catalog. If a web addition reports `filesChecked: false`, the preview covers selection and targets only; the actual transaction checks generated-file conflicts before committing. Additions require current registry receipts and preserve the selected runtime layout. `doctor --providers --json` checks access without configuring infrastructure or certifying production.
10
12
  4. Implement screens, APIs, persistence, authorization and integration behavior. Replace placeholders with working flows. Configure real secrets, origins and reviewed migrations using provider tools; starters do not establish setup completion. Keep credentials out of source, logs and handoffs.
11
13
 
14
+ ## Provider authentication
15
+
16
+ Run `anhedral auth <directory>` for the selected stack. `--status` checks existing access without opening login; `--provider <name>` limits the check to a required provider. JSON and `--non-interactive` never start login prompts. Missing credentials, insufficient permissions and unverified access return a nonzero exit status. Environment-supplied API credentials stay out of output and committed configuration. Authentication does not activate subscriptions, select hosting audience or configure integration resources.
17
+
12
18
  ## Source and release authority
13
19
 
20
+ Complete the selected integrations' nonsecret account/resource choices in the `providers` section of `anhedral.json`. See [provider configuration](provider-configuration.md) for supported adapters, management credentials, private runtime files, retry behavior, provider prerequisites and verification limits. `ship --dry-run` previews their missing settings without provider operations.
21
+
14
22
  Use customer-owned accounts and a reviewed clean commit. Default to a private repository in the selected account; organizations require selection.
15
23
 
16
24
  ```sh
@@ -23,19 +31,20 @@ Choose one release path per change: checked `ship`, or checks followed by an aut
23
31
 
24
32
  ## Cloudflare delivery
25
33
 
26
- Vinext/Workers is the default web recipe. Explicit Next.js on Workers uses `--next --hosting=cloudflare`. Select persistence, identity and AI from the standard. Cloudflare manifests use `anhedral.project.json`; mixed apps append `--provider cloudflare` to lifecycle operations.
34
+ Vinext/Workers is the default web recipe. Explicit Next.js on Workers uses `--next --hosting=cloudflare`. Select persistence, identity and AI from the standard. Cloudflare delivery reads the `cloudflare` section of `anhedral.json`. Default `ship` coordinates Cloudflare services before the Vercel web app in mixed projects. Use `--provider cloudflare` or `--provider vercel` to operate on one hosting target explicitly; standalone `provision` is Cloudflare-only. Supported Cloudflare selections use Void, while explicit OpenNext, queue/DLQ and Basin selections use Wrangler.
27
35
 
28
36
  ```sh
29
37
  anhedral connect my-app --audience private --allow-email owner@example.com
30
38
  anhedral provision my-app --dry-run --json
31
- anhedral provision my-app --json
32
39
  anhedral ship my-app --dry-run --json
33
40
  anhedral ship my-app --json
34
41
  ```
35
42
 
36
43
  Connect verifies the sole accessible or explicitly selected `--account` and preserves audience/account choices. Public access requires authorization. Private hosting needs Zero Trust and scoped Access/Workers permissions; verify routes, domains and previews before and after deployment. Whole-Worker Access does not cover WebSockets: design and verify private realtime separately.
37
44
 
38
- Provision reconciles D1, private R2, KV and Queues/dead-letter queues; it does not implement schemas or integrations. Configure reviewed migrations, direct Neon (or selected Hyperdrive), Basin and external providers separately. The Neon starter uses direct serverless HTTP with a server-side DATABASE_URL. Reconcile partial operations before retrying. Shipping requires clean source, checks account/bindings, runs application checks and confirms active versions/traffic. Multiple Workers are not an atomic release; web deploys last by default.
45
+ For Void projects, `provision` reports the resource plan and defers writes to Void deployment. It never runs Anhedral's resource creator in parallel. The migration owner prepares an ignored, byte-identical validation copy from `packages/db/drizzle`; Void validates its apply set against the shared SQL. Other consumers receive no migration copy. Generate and review SQL with the shared Drizzle configuration first; Void does not inspect shared-package schema drift automatically. Void deploys targets serially, records actual IDs in each app's `void.lock.json`, and applies reviewed deployment migrations. The first activation may require reviewing and committing new locks before shipping a clean release; successful target activation is recorded separately from source completion and product verification. Subsequent deployments reuse the committed identities. Wrangler provisioning reconciles D1, private R2, KV and Queues/dead-letter queues; it does not implement schemas or integrations. Full `ship` also configures the selected integration adapters and private Basin streams. Review database migrations and application-specific integrations separately; developer-added Hyperdrive, Basin sinks and transforms need an explicit provider workflow. Void apps use `anhedral.cloudflare.json`, `void.config.ts` and `env.ts`; copy `env.example` to the app's private `.env`. Do not add `.env.local`, `.env.production`, `.env.example` or `.dev.vars` alongside Void's local environment file. Secret commands use noninteractive stdin; public build variables stay in the build environment. Vite clients use `VITE_*`; the pinned Vinext plugin loads the app `.env` for local builds and maps `NEXT_PUBLIC_*` into client bundles. Supply the selected public values during production builds; server-secret uploads do not configure client bundles. The Neon starter uses direct serverless HTTP with a server-side DATABASE_URL. Reconcile partial operations before retrying. Shipping requires clean source, checks account/bindings, runs application checks and confirms active versions/traffic. Void's pinned structured JSONL receipt is correlated with the active Cloudflare version independently; diagnostic prose is never a success receipt. Missing/ambiguous receipts or provider drift stop acceptance. Multiple Workers are not an atomic release; web deploys last by default. Code rollback delegates to Void for Void projects and does not undo database migrations or incompatible Durable Object class changes.
46
+
47
+ See [Void verification and handoff](void-verification.md) for the pinned evidence contract, reproducible checks, live acceptance results and outstanding gates.
39
48
 
40
49
  ## Native Next.js/Vercel delivery
41
50
 
@@ -52,6 +61,10 @@ anhedral verify my-app --json
52
61
 
53
62
  Connect checks project/framework/root, repository link and audience. New private projects establish independently verified all-deployment Vercel Authentication before code or Git deployment. Hosting membership is separate from product identity; do not add members, seats or paid upgrades automatically. Existing protection changes need authorization. Mixed apps provision/ship Cloudflare services first, then verify the web-to-service flow.
54
63
 
64
+ ## Mobile build handoff
65
+
66
+ Use `ship --platform ios|android --profile <eas-profile>`. Set an explicit Expo owner and slug in static `app.json`; project creation/linking stops for review and a commit. Subsequent builds check the linked identity, configure only public mobile keys, and use the pinned EAS CLI. A queued build returns a build-page link; repeat the same command to inspect that build without submitting another. Completed artifacts must match the selected project and source commit before returning a download URL. It does not submit to a store. Simulator builds cannot be submitted to TestFlight. Signed iOS builds require Apple credentials; Android APK builds can be installed directly.
67
+
55
68
  ## Acceptance and operating limits
56
69
 
57
70
  Run relevant lint/types/Fallow, dependency audits, meaningful tests and actual runtime builds. Exercise browser flows, installed extension permissions, packaged desktop behavior and signed/native device flows where selected. Deployment or HTTP 200 alone does not establish product completion.
@@ -62,15 +75,15 @@ Record service quotas, maximum retries/concurrency/AI work, alert ownership and
62
75
 
63
76
  ## Operations and handoff
64
77
 
65
- | Command | Boundary |
66
- | --- | --- |
67
- | `register` | Stable app identity; generated apps register automatically. |
68
- | `status --refresh` | Independently refresh provider state. |
69
- | `manage` / `manage --local` | Provider overview / explicitly historical local view. |
70
- | `adopt` | Verify active Vercel Git source/repository and record its checked release; no push/deploy. |
71
- | `recover` | Reconcile current provider state after cloning; no invented historical tests/releases. |
72
- | `verify` | Run meaningful root `test:live` with actual URL/release and source/provider checks. |
73
- | `rollback --release <id> --data-compatible` | Restore recorded code after compatibility review; no migration reversal/data restore. |
78
+ | Command | Boundary |
79
+ | ------------------------------------------- | ------------------------------------------------------------------------------------------ |
80
+ | `register` | Stable app identity; generated apps register automatically. |
81
+ | `status --refresh` | Independently refresh provider state. |
82
+ | `manage` / `manage --local` | Provider overview / explicitly historical local view. |
83
+ | `adopt` | Verify active Vercel Git source/repository and record its checked release; no push/deploy. |
84
+ | `recover` | Reconcile current provider state after cloning; no invented historical tests/releases. |
85
+ | `verify` | Run meaningful root `test:live` with actual URL/release and source/provider checks. |
86
+ | `rollback --release <id> --data-compatible` | Restore recorded code after compatibility review; no migration reversal/data restore. |
74
87
 
75
88
  Open the actual app URL or installable artifact and exercise acceptance. Maintain the application's existing `docs/verification.md`: exact versions, source/release, repository, provider identity, audience, configured versus tested integrations, reproducible results and remaining actions. Refresh after changes; acceptance becomes stale when production changes. After rollback, restore matching clean source before verifying.
76
89
 
@@ -78,6 +91,8 @@ Committed manifests preserve identity. Ignored `.anhedral/` receipts are local h
78
91
 
79
92
  ## Evidence and maintenance
80
93
 
81
- Local/mocked coverage is distinct from live GitHub/Vercel private setup, fresh-clone recovery, installed fresh-chat workflow and connected integrations. Retained HTTP/CRUD/redeploy/rollback runs prove only their tested profile. Sites' inventory, visitor connectors and managed sharing require separate platform implementation. No operated managed backend or issued app URL is established here; see the [managed contract](https://github.com/anhedral/anhedral-init/blob/main/docs/managed-hosting-architecture.md).
82
-
83
94
  Before release, check the exact candidate's runtime, current dependency advisories, remote CI, installed-plugin and selected provider/native acceptance. Unresolved high-severity production audit failures block shipping. Keep dated results with release/test artifacts. Update this guide when commands, lifecycle or acceptance requirements change, and regenerate its bundled plugin copy.
95
+
96
+ ### Interrupted local delivery locks
97
+
98
+ Use `anhedral recover --lock [directory]` only after an interrupted command. This releases a lock only when its recorded process is proven dead on the same host. It never replays provider operations or deletes delivery receipts. Inspect status and receipts before retrying. Live, foreign, malformed, and uncertain locks are preserved. A leftover `.anhedral/ship.guard` requires manual inspection; the CLI cannot safely infer its ownership. Do not combine local lock recovery with `--provider` or `--refresh`.
@@ -0,0 +1,102 @@
1
+ # Anhedral project dashboard
2
+
3
+ Anhedral is headless-first: describe the application to Codex, review the selected stack, develop its features, authenticate to your providers and ship through the CLI. The optional dashboard starts with the same local evidence available from `anhedral inspect --json`. Opening it or refreshing the project performs no provider calls. Explicit service controls request live status, analytics or data through the shared CLI adapters.
4
+
5
+ Building or packaging the plugin does not install or publish it. Actual Codex host rendering and composer behavior require separate verification; protocol tests do not establish those behaviors.
6
+
7
+ ## Project lifecycle
8
+
9
+ The overview begins with **Init → Auth → Ship**, derived by the same inspector used by the CLI. Init reports supported Anhedral configuration and local structural readiness. Auth lists selected providers and recorded account references; these are not proof of a valid session, permission or billing eligibility. Ship summarizes per-target success receipts and flags incomplete operations, conflicts and deletion history. A recorded success does not establish current source or live health.
10
+
11
+ Review source, provider access and shipping plan prepare unsent Codex drafts. They do not run commands directly. The workflow is equally usable through the headless CLI. Services remain a secondary, project-scoped view. Registering an arbitrary directory does not adopt its stack or activate lifecycle actions; supported Anhedral configuration must exist. There is no separate Anhedral account or hosted control plane.
12
+
13
+ ## Screens and evidence
14
+
15
+ | Screen | Information | Evidence boundary |
16
+ | --- | --- | --- |
17
+ | Overview | Project identity, stack selection, per-target latest attempt and last success | Recorded results; not live health or feature acceptance |
18
+ | Services | Application targets, configured bindings, provisioning receipts and selected integrations | Local inventory plus explicitly requested live readings; receipt matching uses resource kind and identifiers |
19
+ | Stack | Workspace package dependencies, declared bindings, environment names and cron expressions | Package dependencies do not prove network calls; declarations do not prove resource existence |
20
+ | Setup | Local prerequisites, selected providers, capability limits and setup guidance | Authentication, selected-account permission and billing remain not checked |
21
+ | Delivery | Separate Cloudflare, Vercel and mobile records; integration pending outcomes and latest operation | One provider's success does not establish another's; old running records do not prove a process is active |
22
+
23
+ Service controls expose only implemented readers; there is no schedule-execution reader. Environment names come from example files and reveal no values or proof of secret validity. Mobile download URLs may contain access tokens and are excluded; validated Expo build-page links may be displayed. Missing record timestamps and project identity are unavailable rather than invented.
24
+
25
+ Every section is bounded and validated independently. A corrupt provider journal must not hide another target's valid evidence. Read time is explicitly distinct from receipt time. Configured, recorded and unknown states must remain distinguishable. General secret files, provider credential vaults, runtime state, raw diagnostics and absolute source paths are excluded from the UI projection.
26
+
27
+ ## Interactions
28
+
29
+ New project opens a new composer with this prompt, without sending: “Create a new project using [@Anhedral](plugin://anhedral@anhedral). Start by explaining the stack and asking me what it should be about.” Setup and delivery actions prepare unsent drafts for the current conversation. The user reviews and sends the request before Codex acts. Unsupported hosts offer copyable text. Project selection updates authorized model context; it does not execute commands.
30
+
31
+ Refresh reloads local files only. Rename and forget affect only local catalog metadata, never project source or provider resources. There is no project-creation or registration dialog. Successful `anhedral init` automatically registers its generated source in the local catalog. Existing sources can be registered through the local operator command. MCP tool inputs accept project IDs rather than arbitrary filesystem paths.
32
+
33
+ ## Installation
34
+
35
+ Install with `codex plugin marketplace add anhedral/anhedral-cli`, then `codex plugin add anhedral@anhedral`. The marketplace references `plugin-v<version>` in the same repository. The release workflow creates this immutable tag from the verified ZIP, including its generated runtime; the development source directory alone is not an installable release. Plugin source tags retain the reviewed release commit as their parent. Existing tags cannot be replaced by the release workflow.
36
+
37
+ ## Local development
38
+
39
+ The UI toolchain requires Node 22.13+ within Node 22, or Node 24+. The CLI retains its separately documented engines.
40
+
41
+ ```sh
42
+ pnpm install --frozen-lockfile
43
+ pnpm --dir plugins/codex/inspector install --frozen-lockfile
44
+ pnpm build
45
+ pnpm plugin:check
46
+ pnpm --dir plugins/codex/inspector exec playwright install chromium
47
+ pnpm --dir plugins/codex/inspector test:browser
48
+ ANHEDRAL_PLUGIN_DATA="$PWD/.artifacts/plugin-preview" node plugins/codex/inspector/dist/server.mjs register "$PWD" "Anhedral"
49
+ ANHEDRAL_PLUGIN_DATA="$PWD/.artifacts/plugin-preview" pnpm plugin:preview
50
+ ```
51
+
52
+ Open `http://127.0.0.1:4317/`. The preview binds only to loopback, validates Host/Origin, bounds requests and uses a restrictive content security policy. `anhedral inspect [directory] --json` provides the shared read-only projection directly. `anhedral registry capabilities --json` explains the supported automation and owner steps.
53
+
54
+ `src/project-inspector.ts` owns projection; `src/catalog-snapshot.ts` adds catalog identity. The browser only renders its validated schema. The MCP server exposes `open_projects`, `list_projects`, `get_project`, `get_project_services`, local metadata tools and model-only source/catalog context tools. They remain useful without UI rendering. Standard MCP Apps resources and bridge messages provide the optional panel, host themes and inline/fullscreen modes. Native host-specific draft support is a separate acceptance gate.
55
+
56
+ The plugin and standalone CLI share one private catalog. List views read bounded summaries; only a selected project loads detailed inspection. The server does not scan for other projects. CLI initialization registers new apps using the persistent `identity.id` in `anhedral.json`; recreating a directory creates a separate app rather than silently retargeting an old catalog entry. A remote server cannot inspect these local directories without a separately reviewed architecture; never publish the local catalog through a tunnel.
57
+
58
+ ## Recovery and release review
59
+
60
+ Interrupted catalog writers can be inspected and recovered with the same private catalog directory:
61
+
62
+ ```sh
63
+ ANHEDRAL_PLUGIN_DATA="$PWD/.artifacts/plugin-preview" node plugins/codex/inspector/dist/server.mjs recover-catalog-lock
64
+ ```
65
+
66
+ Only a proven dead same-host owner permits recovery. Live, foreign, malformed and uncertain owners remain blocked. Recovery changes catalog access only, not provider work or delivery state.
67
+
68
+ Build/package checks bind the runtime and self-contained browser HTML to source and CLI version. Exact ZIP protocol tests exercise resources, schemas and headless tools. Before publication, verify native host entrypoints, unsent drafts, theme/reload behavior, all supported sections, keyboard navigation and narrow screens against the exact rebuilt ZIP. Publication remains a separate reviewed action.
69
+
70
+ The design follows the official [optional UI guidance](https://developers.openai.com/plugins/concepts/plugins#optional-ui) and [MCP Apps foundation](https://developers.openai.com/plugins/build/chatgpt-ui#start-with-mcp-apps).
71
+
72
+ ## Live service capabilities
73
+
74
+ Live readings require the selected provider account and resource permissions. Missing access, unavailable providers and absent resources are distinct from a successful reading. Analytics show their source, UTC window and sampling status; recorded deployment success does not imply current health.
75
+
76
+ | Service | Status | Analytics | Data | Confirmed deletion |
77
+ | --- | --- | --- | --- | --- |
78
+ | Cloudflare Worker | Settings existence | Requests, errors and CPU quantiles | — | — |
79
+ | D1 | Resource identity and current storage | Daily query/row counts and latency | Bounded table pages | Project-created, unshared resources |
80
+ | KV | Resource identity | — | Paginated key metadata; no values | Project-created, unshared resources |
81
+ | R2 | Bucket identity | — | Paginated object metadata; no contents | — |
82
+ | Queues | Resource identity | — | — | — |
83
+ | Vercel | Project/deployment status | Daily Web Analytics | — | — |
84
+ | Neon | Project identity | — | Bounded public-table pages | — |
85
+ | PostHog | Project identity | Hourly events and distinct IDs per bucket | — | — |
86
+ | Clerk, Resend, Stripe, RevenueCat, Sentry, OpenAI | Selected integration identity | — | — | — |
87
+
88
+ Neon browsing requires `ANHEDRAL_NEON_READONLY_URL`, optionally suffixed with the uppercase project ID (hyphens replaced by underscores). The endpoint must belong to that project. Each read transaction verifies a restricted role and read-only mode. Sensitive columns are masked before fetching; arbitrary SQL is not accepted.
89
+
90
+ R2 metadata browsing requires bucket-scoped read-only S3 credentials in `ANHEDRAL_R2_ACCESS_KEY_ID` and `ANHEDRAL_R2_SECRET_ACCESS_KEY`, optionally suffixed with the uppercase account ID. The reader signs only the selected account/bucket request and never downloads object contents.
91
+
92
+ Data rows, table names and deletion confirmation tokens are returned through private app metadata rather than model-visible MCP results. CLI data output is explicit user-requested output. Data views mask sensitive fields and do not provide an unmask control. D1 and Neon project bounded columns and mask sensitive columns in SQL before fetching rows; empty tables retain their schema. Database pages use explicit ordering, but concurrent writes can still change offset-based pages. KV and R2 metadata pages use provider cursors.
93
+
94
+ Deletion is intentionally limited to D1 and KV. Review shows the exact account, resource, affected applications and impact. The user must type the resource name. The server requires a short-lived, single-use token, revalidates source and provider identity, and rejects adopted resources or detected external Worker consumers. Provider reads cannot provide an atomic lock against another operator changing remote dependencies.
95
+
96
+ A deletion request is never automatically retried. Confirmed absence is required to report success. Pending or uncertain outcomes remain recorded across reloads and block automatic reprovisioning. Source bindings remain for explicit review before shipping; removing a service does not silently rewrite application code. This implementation does not delete whole applications or provider accounts.
97
+
98
+ The CLI shares these adapters: `anhedral services list --json` lists exact selectors; `anhedral help services` describes status, metrics, tables, data and the two-step deletion flow. No service operation provisions resources, changes billing or deploys code.
99
+
100
+ The catalog defaults to `~/.local/share/anhedral/projects`; `ANHEDRAL_PLUGIN_DATA` selects an alternate directory and `ANHEDRAL_DISABLE_CATALOG=1` disables initialization registration. A catalog failure leaves successfully generated source intact and reports a registration recovery action.
101
+
102
+ The inspector source lives in `plugins/codex/inspector`; the installable plugin source lives in `plugins/codex/distribution`. Packaging reads that directory and emits a self-contained ZIP. Immutable `plugin-v*` release tags retain the public `plugins/anhedral` installation path used by the marketplace; the publication script builds that tree from the verified ZIP. That release path is independent of the development checkout layout.