anhedral 0.17.0 → 0.18.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 (105) hide show
  1. package/README.md +33 -68
  2. package/assets/contracts/LICENSE +201 -0
  3. package/assets/contracts/LICENSE.environment +201 -0
  4. package/assets/contracts/LICENSE.operations +201 -0
  5. package/assets/contracts/deployment-provenance.json +15 -0
  6. package/assets/contracts/environment-provenance.json +11 -0
  7. package/assets/contracts/operations-provenance.json +11 -0
  8. package/assets/launch/application.server.ts.txt +13 -0
  9. package/assets/launch/auth-client.ts.txt +4 -0
  10. package/assets/launch/home.tsx.txt +20 -0
  11. package/assets/launch/minimal-application.server.ts.txt +5 -0
  12. package/assets/launch/minimal-server.ts.txt +7 -0
  13. package/assets/launch/request-context.ts.txt +3 -0
  14. package/assets/launch/root.tsx.txt +27 -0
  15. package/assets/launch/router.tsx.txt +21 -0
  16. package/assets/launch/server.ts.txt +13 -0
  17. package/assets/launch/sign-in.tsx.txt +53 -0
  18. package/assets/launch/styles.css.txt +19 -0
  19. package/assets/security/credential-patterns.d.mts +3 -0
  20. package/assets/security/credential-patterns.mjs +59 -0
  21. package/assets/stack/api-index.ts.txt +6 -1
  22. package/assets/stack/event-retention.sql.txt +10 -0
  23. package/assets/stack/stripe.ts.txt +30 -13
  24. package/dist/bin.js +55 -36
  25. package/dist/capabilities.d.ts +1 -1
  26. package/dist/capability-catalog.d.ts +44 -11
  27. package/dist/capability-catalog.js +96 -11
  28. package/dist/capability-command.d.ts +2 -2
  29. package/dist/capability-command.js +178 -27
  30. package/dist/capability-editor.js +6 -5
  31. package/dist/capability-recipes.js +54 -6
  32. package/dist/cli-arguments.d.ts +2 -0
  33. package/dist/cli-arguments.js +101 -50
  34. package/dist/cli-commands.d.ts +1 -1
  35. package/dist/cli-commands.js +30 -6
  36. package/dist/cli-errors.d.ts +18 -0
  37. package/dist/cli-errors.js +63 -0
  38. package/dist/cli-output.d.ts +22 -0
  39. package/dist/cli-output.js +42 -7
  40. package/dist/command-runner.d.ts +1 -0
  41. package/dist/command-runner.js +88 -0
  42. package/dist/command-schema.d.ts +16 -0
  43. package/dist/command-schema.js +390 -21
  44. package/dist/completion.d.ts +2 -0
  45. package/dist/completion.js +201 -0
  46. package/dist/composition.d.ts +35 -0
  47. package/dist/composition.js +28 -0
  48. package/dist/contracts/cli-transport.d.ts +217 -0
  49. package/dist/contracts/cli-transport.js +167 -0
  50. package/dist/contracts/deployment.d.ts +282 -0
  51. package/dist/contracts/deployment.js +234 -0
  52. package/dist/contracts/environment-file.d.ts +7 -0
  53. package/dist/contracts/environment-file.js +112 -0
  54. package/dist/contracts/environment-transport.d.ts +79 -0
  55. package/dist/contracts/environment-transport.js +110 -0
  56. package/dist/contracts/runtime-logs-transport.d.ts +127 -0
  57. package/dist/contracts/runtime-logs-transport.js +50 -0
  58. package/dist/contracts/source-bundle.d.ts +11 -0
  59. package/dist/contracts/source-bundle.js +197 -0
  60. package/dist/contracts/source-profile.d.ts +4 -0
  61. package/dist/contracts/source-profile.js +5 -0
  62. package/dist/contracts/staging-transport.d.ts +79 -0
  63. package/dist/contracts/staging-transport.js +43 -0
  64. package/dist/dependencies.d.ts +10 -1
  65. package/dist/dependencies.js +18 -1
  66. package/dist/index.d.ts +6 -0
  67. package/dist/index.js +4 -0
  68. package/dist/launch.d.ts +21 -0
  69. package/dist/launch.js +250 -0
  70. package/dist/platform-command.d.ts +9 -0
  71. package/dist/platform-command.js +584 -0
  72. package/dist/platform-environment.d.ts +18 -0
  73. package/dist/platform-environment.js +257 -0
  74. package/dist/platform-operations.d.ts +26 -0
  75. package/dist/platform-operations.js +155 -0
  76. package/dist/platform-source.d.ts +8 -0
  77. package/dist/platform-source.js +111 -0
  78. package/dist/platform-state.d.ts +13 -0
  79. package/dist/platform-state.js +207 -0
  80. package/dist/platforms/tanstack.d.ts +8 -0
  81. package/dist/platforms/tanstack.js +155 -0
  82. package/dist/registry/options.js +34 -31
  83. package/dist/registry/usage.d.ts +4 -1
  84. package/dist/registry/usage.js +58 -4
  85. package/dist/scaffold/styling.d.ts +1 -1
  86. package/dist/scaffold/workspace.js +11 -1
  87. package/dist/stack-registry.d.ts +2 -2
  88. package/dist/standard.js +21 -6
  89. package/dist/transaction.js +28 -3
  90. package/dist/ui-command.d.ts +4 -2
  91. package/dist/ui-command.js +79 -38
  92. package/dist/ui-project.d.ts +2 -0
  93. package/dist/ui-project.js +38 -8
  94. package/dist/util.js +40 -61
  95. package/dist/version.d.ts +1 -1
  96. package/dist/version.js +1 -1
  97. package/docs/capabilities.md +22 -88
  98. package/docs/software-factory.md +169 -9
  99. package/docs/stack-standard.md +7 -17
  100. package/docs/ui.md +9 -22
  101. package/package.json +27 -20
  102. package/docs/anhedral-stack.md +0 -12
  103. package/docs/assets/anhedral-stack-light.png +0 -0
  104. package/docs/assets/anhedral-stack.png +0 -0
  105. package/docs/native-ui.md +0 -47
@@ -3,10 +3,13 @@ export const GLOBAL_OPTIONS = [
3
3
  flag: '--cwd',
4
4
  aliases: ['-c'],
5
5
  value: 'directory',
6
+ kind: 'directory',
6
7
  arity: 'required',
7
8
  description: 'Run from a selected working directory.',
8
9
  },
9
10
  { flag: '--json', description: 'Return machine-readable output.' },
11
+ { flag: '--human', description: 'Explicitly format Platform output for people.' },
12
+ { flag: '--non-interactive', description: 'Never prompt or start interactive approval polling.' },
10
13
  {
11
14
  flag: '--quiet',
12
15
  aliases: ['-q'],
@@ -25,11 +28,320 @@ export function optionHelp(option) {
25
28
  return `${flags}${argument} ${option.description}`;
26
29
  }
27
30
  export function commandDefinition(command) {
28
- return COMMANDS[command ?? ''];
31
+ return command && Object.hasOwn(COMMANDS, command) ? COMMANDS[command] : undefined;
29
32
  }
33
+ const PLATFORM_OPTIONS = [
34
+ {
35
+ flag: '--api-url',
36
+ value: 'origin',
37
+ arity: 'required',
38
+ description: 'Explicit Platform API origin; defaults to https://platform.anhedral.com.',
39
+ },
40
+ {
41
+ flag: '--credential-file',
42
+ value: 'file',
43
+ kind: 'file',
44
+ arity: 'required',
45
+ description: 'Explicit owner-only credential file instead of the OS secret store.',
46
+ },
47
+ ];
48
+ const ENVIRONMENT_OPTIONS = [
49
+ ...PLATFORM_OPTIONS,
50
+ {
51
+ flag: '--environment',
52
+ value: 'staging|production',
53
+ arity: 'required',
54
+ choices: ['staging', 'production'],
55
+ description: 'Select the target environment explicitly.',
56
+ },
57
+ {
58
+ flag: '--file',
59
+ value: 'file',
60
+ kind: 'file',
61
+ arity: 'required',
62
+ description: 'Read an owner-only UTF-8 file (up to64KiB); never put values in arguments.',
63
+ },
64
+ { flag: '--stdin', description: 'Read private UTF-8 input from a pipe.' },
65
+ {
66
+ flag: '--type',
67
+ value: 'secret|config',
68
+ arity: 'required',
69
+ choices: ['secret', 'config'],
70
+ description: 'Set the variable type; public prefixes default to config, others to secret.',
71
+ },
72
+ {
73
+ flag: '--replace',
74
+ description: 'Explicitly allow replacing existing variables with version checks.',
75
+ },
76
+ { flag: '--new', description: 'Start another import instead of resuming saved identity.' },
77
+ { flag: '--dry-run', description: 'Validate input locally and print names and types only.' },
78
+ ];
79
+ const STAGING_OPTIONS = [
80
+ ...PLATFORM_OPTIONS,
81
+ {
82
+ flag: '--candidate',
83
+ value: 'uuid',
84
+ arity: 'required',
85
+ description: 'Select a ready, runtime-verified deployment candidate.',
86
+ },
87
+ { flag: '--new', description: 'Start a new staging deployment using the current generation.' },
88
+ ];
30
89
  export const COMMANDS = {
90
+ completion: {
91
+ description: 'Print an offline shell completion script.',
92
+ usage: 'completion <bash|zsh>',
93
+ options: [],
94
+ positional: { name: 'shell', min: 1, max: 1, kind: 'value', choices: ['bash', 'zsh'] },
95
+ examples: ['completion bash', 'completion zsh'],
96
+ note: 'Prints the script only; never edits your shell profile or contacts Platform.',
97
+ },
98
+ login: {
99
+ description: 'Approve a short-lived CLI session in your browser.',
100
+ usage: 'login [--start|--resume]',
101
+ options: [
102
+ ...PLATFORM_OPTIONS,
103
+ { flag: '--start', description: 'Start approval and return without polling.' },
104
+ { flag: '--resume', description: 'Resume saved browser approval.' },
105
+ ],
106
+ conflicts: [['--start', '--resume']],
107
+ examples: ['login', 'login --start --json', 'login --resume'],
108
+ note: 'Device secrets and API tokens stay in your credential store. Server CLI access must be configured.',
109
+ },
110
+ logout: {
111
+ description: 'Revoke this CLI session.',
112
+ usage: 'logout',
113
+ options: PLATFORM_OPTIONS,
114
+ examples: ['logout'],
115
+ note: 'Revokes server access before clearing local credentials.',
116
+ },
117
+ whoami: {
118
+ description: 'Show the current CLI identity.',
119
+ usage: 'whoami',
120
+ options: [
121
+ ...PLATFORM_OPTIONS,
122
+ {
123
+ flag: '--context',
124
+ description: 'Include local project and credential provenance without exposing secrets.',
125
+ },
126
+ ],
127
+ examples: ['whoami --json', 'whoami --context --human'],
128
+ },
129
+ link: {
130
+ description: 'Link this workspace to an existing project.',
131
+ usage: 'link --project <uuid> --team <uuid>',
132
+ options: [
133
+ ...PLATFORM_OPTIONS,
134
+ { flag: '--project', value: 'uuid', arity: 'required', description: 'Existing project ID.' },
135
+ { flag: '--team', value: 'uuid', arity: 'required', description: 'Owning team ID.' },
136
+ ],
137
+ examples: ['link --project <uuid> --team <uuid>'],
138
+ note: 'Requires current project build access. Existing application identities are preserved.',
139
+ },
140
+ unlink: {
141
+ description: 'Remove the local project link.',
142
+ usage: 'unlink',
143
+ options: PLATFORM_OPTIONS,
144
+ examples: ['unlink'],
145
+ },
146
+ deploy: {
147
+ description: 'Plan deployment and reserve a candidate from sealed source.',
148
+ usage: 'deploy <plan|prepare|status> [options]',
149
+ options: [
150
+ ...PLATFORM_OPTIONS,
151
+ {
152
+ flag: '--manifest',
153
+ value: 'file',
154
+ kind: 'file',
155
+ arity: 'required',
156
+ description: 'Explicit deployment manifest matching sealed source.',
157
+ },
158
+ {
159
+ flag: '--new',
160
+ description: 'Explicitly create a new plan request after inputs or routing change.',
161
+ },
162
+ ],
163
+ children: {
164
+ plan: {
165
+ description: 'Plan a candidate from the saved sealed source.',
166
+ usage: 'deploy plan --manifest <file> [--new]',
167
+ options: [
168
+ ...PLATFORM_OPTIONS,
169
+ {
170
+ flag: '--manifest',
171
+ value: 'file',
172
+ kind: 'file',
173
+ arity: 'required',
174
+ description: 'Deployment manifest matching sealed source.',
175
+ },
176
+ { flag: '--new', description: 'Explicitly create a new plan request.' },
177
+ ],
178
+ examples: [
179
+ 'deploy plan --manifest deployment.json',
180
+ 'deploy plan --manifest deployment.json --json',
181
+ ],
182
+ },
183
+ prepare: {
184
+ description: 'Reserve an immutable candidate from the saved plan.',
185
+ usage: 'deploy prepare',
186
+ options: PLATFORM_OPTIONS,
187
+ examples: ['deploy prepare', 'deploy prepare --json'],
188
+ },
189
+ status: {
190
+ description: 'Inspect the saved deployment plan or candidate.',
191
+ usage: 'deploy status',
192
+ options: PLATFORM_OPTIONS,
193
+ examples: ['deploy status', 'deploy status --json'],
194
+ },
195
+ },
196
+ examples: ['deploy plan --manifest deployment.json', 'deploy prepare', 'deploy status'],
197
+ note: 'Preparation reserves a candidate; server policy controls build admission. No preview or deployment is activated.',
198
+ },
199
+ env: {
200
+ description: 'Manage project configuration and write-only secrets through Platform.',
201
+ usage: 'env <list|import|set> [options]',
202
+ options: ENVIRONMENT_OPTIONS,
203
+ children: {
204
+ list: {
205
+ description: 'List names, types and versions; values are never returned.',
206
+ usage: 'env list [--environment staging|production]',
207
+ options: ENVIRONMENT_OPTIONS.filter((option) => ['--api-url', '--credential-file', '--environment'].includes(option.flag)),
208
+ examples: ['env list --json'],
209
+ },
210
+ import: {
211
+ description: 'Import a private dotenv file atomically.',
212
+ usage: 'env import --environment staging|production --file <file> [--replace] [--new]',
213
+ options: ENVIRONMENT_OPTIONS,
214
+ examples: [
215
+ 'env import --environment staging --file .env.local --dry-run',
216
+ 'env import --environment production --stdin --replace --new',
217
+ ],
218
+ },
219
+ set: {
220
+ description: 'Set one variable from a private file or stdin.',
221
+ usage: 'env set <NAME> --environment staging|production --stdin [--replace] [--new]',
222
+ options: ENVIRONMENT_OPTIONS,
223
+ positional: { name: 'NAME', min: 1, max: 1 },
224
+ examples: ['env set SERVICE_API_KEY --environment staging --stdin'],
225
+ },
226
+ },
227
+ conflicts: [['--file', '--stdin']],
228
+ examples: ['env list', 'env import --environment staging --file .env.local --dry-run'],
229
+ note: 'Values never appear in output or retry state. Platform enforces project roles and production approvals; saving configuration does not change an existing deployment.',
230
+ },
231
+ staging: {
232
+ description: 'Manage persistent staging deployments for the linked project.',
233
+ usage: 'staging <status|deploy> [options]',
234
+ options: STAGING_OPTIONS,
235
+ positional: { name: 'operation', min: 1, max: 1, choices: ['status', 'deploy'] },
236
+ children: {
237
+ status: {
238
+ description: 'Read staging history and active deployment.',
239
+ usage: 'staging status',
240
+ options: PLATFORM_OPTIONS,
241
+ positional: { name: 'operation', min: 0, max: 0 },
242
+ examples: ['staging status --json'],
243
+ },
244
+ deploy: {
245
+ description: 'Deploy a ready candidate to staging.',
246
+ usage: 'staging deploy --candidate <uuid> [--new]',
247
+ options: STAGING_OPTIONS,
248
+ positional: { name: 'operation', min: 0, max: 0 },
249
+ examples: ['staging deploy --candidate <uuid>'],
250
+ },
251
+ },
252
+ examples: ['staging status', 'staging deploy --candidate <uuid>'],
253
+ note: 'Retried requests retain the same identity and generation. Configuration is frozen for each new staging deployment; production approval stays in Platform.',
254
+ },
255
+ logs: {
256
+ description: 'Read redacted runtime logs for the linked project.',
257
+ usage: 'logs [options]',
258
+ positional: { name: 'arguments', min: 0, max: 0 },
259
+ options: [
260
+ ...PLATFORM_OPTIONS,
261
+ {
262
+ flag: '--environment',
263
+ value: 'staging|production',
264
+ arity: 'required',
265
+ choices: ['staging', 'production'],
266
+ description: 'Choose the environment (default: staging).',
267
+ },
268
+ {
269
+ flag: '--deployment',
270
+ value: 'uuid',
271
+ arity: 'required',
272
+ description: 'Filter one deployment.',
273
+ },
274
+ {
275
+ flag: '--level',
276
+ value: 'level',
277
+ arity: 'required',
278
+ choices: ['debug', 'info', 'warn', 'error'],
279
+ description: 'Filter the event level.',
280
+ },
281
+ {
282
+ flag: '--source',
283
+ value: 'source',
284
+ arity: 'required',
285
+ choices: ['request', 'console', 'exception'],
286
+ description: 'Filter request, console or exception events.',
287
+ },
288
+ {
289
+ flag: '--range',
290
+ value: 'range',
291
+ arity: 'required',
292
+ choices: ['1h', '24h', '7d'],
293
+ description: 'Choose a time range (default: 24h).',
294
+ },
295
+ {
296
+ flag: '--search',
297
+ value: 'text',
298
+ arity: 'required',
299
+ description: 'Search redacted message text.',
300
+ },
301
+ {
302
+ flag: '--cursor',
303
+ value: 'cursor',
304
+ arity: 'required',
305
+ description: 'Read the next page using a returned cursor.',
306
+ },
307
+ ],
308
+ examples: [
309
+ 'logs --environment staging --level error --json',
310
+ 'logs --environment production --range 1h',
311
+ ],
312
+ note: 'Runtime collection is best effort and reports unavailable coverage and dropped events. Retention is seven days; source/build logs remain separate.',
313
+ },
314
+ source: {
315
+ description: 'Upload an immutable source checkpoint with resumable chunks.',
316
+ usage: 'source <upload|status> [options]',
317
+ options: [
318
+ ...PLATFORM_OPTIONS,
319
+ { flag: '--dry-run', description: 'Package and inspect source without upload.' },
320
+ { flag: '--new', description: 'Explicitly start a new request after changing source.' },
321
+ ],
322
+ children: {
323
+ upload: {
324
+ description: 'Upload immutable source, resuming the saved request.',
325
+ usage: 'source upload [--dry-run] [--new]',
326
+ options: [
327
+ ...PLATFORM_OPTIONS,
328
+ { flag: '--dry-run', description: 'Inspect source locally without upload.' },
329
+ { flag: '--new', description: 'Explicitly begin a new immutable request.' },
330
+ ],
331
+ examples: ['source upload --dry-run --json', 'source upload'],
332
+ },
333
+ status: {
334
+ description: 'Read the saved upload receipt.',
335
+ usage: 'source status',
336
+ options: PLATFORM_OPTIONS,
337
+ examples: ['source status', 'source status --json'],
338
+ },
339
+ },
340
+ examples: ['source upload --dry-run', 'source upload', 'source status'],
341
+ note: 'Honors .gitignore, excludes secrets and generated files, rejects symlinks and credential material. Sealing source does not enable hosted admission or deploy.',
342
+ },
31
343
  add: {
32
- description: 'Add selected stack capabilities to an existing Anhedral project.',
344
+ description: 'Add backend, private storage or payments to the Anhedral Stack.',
33
345
  usage: 'add <capabilities...> [options]',
34
346
  options: [
35
347
  { flag: '--with-dependencies', description: 'Explicitly include missing prerequisites.' },
@@ -39,40 +351,76 @@ export const COMMANDS = {
39
351
  description: 'Preview every file and prerequisite without writes or network.',
40
352
  },
41
353
  ],
42
- examples: [
43
- 'add hono',
44
- 'add database-auth',
45
- 'add expo native-ui stripe revenuecat --with-dependencies --dry-run --json',
46
- ],
354
+ positional: { name: 'capabilities', min: 1, max: 50, kind: 'capability' },
355
+ examples: ['add backend', 'add r2', 'add r2 stripe --with-dependencies --dry-run --json'],
47
356
  note: 'Adds source and local configuration only. Existing edits are preserved. No provisioning, credential installation, migration or deployment.',
48
357
  },
49
358
  stack: {
50
- description: 'List capabilities and inspect declared source state.',
359
+ description: 'Inspect the Anhedral Stack and its three optional additions.',
51
360
  usage: 'stack <list|status|doctor>',
52
361
  options: [],
362
+ children: {
363
+ list: {
364
+ description: 'Show the Anhedral Stack foundation and optional additions.',
365
+ usage: 'stack list',
366
+ options: [],
367
+ examples: ['stack list', 'stack list --json'],
368
+ },
369
+ status: {
370
+ description: 'Inspect installed Anhedral Stack additions.',
371
+ usage: 'stack status',
372
+ options: [],
373
+ examples: ['stack status --json'],
374
+ },
375
+ doctor: {
376
+ description: 'Check source completeness and prerequisites.',
377
+ usage: 'stack doctor',
378
+ options: [],
379
+ examples: ['stack doctor', 'stack doctor --json'],
380
+ },
381
+ },
53
382
  examples: ['stack list', 'stack status --json', 'stack doctor'],
54
383
  note: 'Installed source is not proof of live provider activation.',
55
384
  },
56
385
  ui: {
57
- description: 'Anhedral UI: one source-owned catalog for web and native.',
386
+ description: 'Source-owned web UI for the Anhedral Stack.',
58
387
  usage: 'ui <init|add|list|diff|doctor> [components...] [options]',
59
388
  options: [
60
- { flag: '--web', description: 'Select the Next.js application.' },
61
- { flag: '--native', description: 'Select the Expo/NativeWind 4 application.' },
62
- { flag: '--all', description: 'Explicitly select every web/native application.' },
389
+ { flag: '--web', description: 'Select the Anhedral Stack web application.' },
63
390
  { flag: '--dry-run', description: 'Show the installer plan without writes or network.' },
64
391
  ],
65
- examples: [
66
- 'ui list',
67
- 'ui add button --web',
68
- 'ui add button --native',
69
- 'ui diff button',
70
- 'ui doctor',
71
- ],
72
- note: 'Component installation uses the pinned official shadcn CLI. Native falls back to React Native Reusables. No automatic overwrite, provider operations or full-parity promise.',
392
+ children: Object.fromEntries(['init', 'add', 'list', 'diff', 'doctor'].map((action) => [
393
+ action,
394
+ {
395
+ description: {
396
+ init: 'Initialize Anhedral UI configuration.',
397
+ add: 'Install selected UI components.',
398
+ list: 'List available Anhedral Stack web components.',
399
+ diff: 'Inspect differences for selected UI components.',
400
+ doctor: 'Check UI configuration.',
401
+ }[action],
402
+ usage: `ui ${action}${['add', 'diff'].includes(action) ? ' <components...>' : ''} [options]`,
403
+ options: [
404
+ { flag: '--web', description: 'Select the Anhedral Stack web application.' },
405
+ { flag: '--dry-run', description: 'Preview without writes or network.' },
406
+ ],
407
+ positional: {
408
+ name: 'components',
409
+ min: ['add', 'diff'].includes(action) ? 1 : 0,
410
+ max: ['add', 'diff'].includes(action) ? 50 : 0,
411
+ kind: 'component',
412
+ },
413
+ examples: [
414
+ `ui ${action}${['add', 'diff'].includes(action) ? ' button --web' : ''}`,
415
+ `ui ${action}${['add', 'diff'].includes(action) ? ' button --web' : ''} --json`,
416
+ ],
417
+ },
418
+ ])),
419
+ examples: ['ui list', 'ui add button --web', 'ui diff button', 'ui doctor'],
420
+ note: 'Web component installation uses the pinned official shadcn CLI. No automatic overwrite or provider operations.',
73
421
  },
74
422
  init: {
75
- description: 'Scaffold Next.js/OpenNext with source-owned Anhedral UI; add capabilities only when needed.',
423
+ description: 'Create the Anhedral Stack: web UI first, then add backend, storage and payments.',
76
424
  usage: 'init [directory] [options]',
77
425
  options: [
78
426
  { flag: '--skip-install', description: 'Write source without installing dependencies.' },
@@ -80,6 +428,8 @@ export const COMMANDS = {
80
428
  { flag: '--no-git', description: 'Skip Git initialization.' },
81
429
  { flag: '--dry-run', description: 'Preview the foundation without writes or network.' },
82
430
  ],
431
+ positional: { name: 'directory', min: 0, max: 1, kind: 'directory' },
432
+ conflicts: [['--git', '--no-git']],
83
433
  examples: [
84
434
  'init my-app',
85
435
  'init my-app --dry-run --json',
@@ -88,3 +438,22 @@ export const COMMANDS = {
88
438
  note: 'Generated source belongs to you. Application features, authentication, payments and hosting are your responsibility. Init never provisions or deploys resources.',
89
439
  },
90
440
  };
441
+ /** Complete topic lookup; leaf options are contextual while parser acceptance stays compatible. */
442
+ export function commandTopic(topic) {
443
+ let definition = commandDefinition(topic[0]);
444
+ for (const part of topic.slice(1)) {
445
+ if (!definition?.children || !Object.hasOwn(definition.children, part))
446
+ return undefined;
447
+ const child = definition.children[part];
448
+ definition = {
449
+ ...child,
450
+ note: child.note ?? definition.note,
451
+ conflicts: child.conflicts ?? definition.conflicts,
452
+ };
453
+ }
454
+ return definition;
455
+ }
456
+ /** Family options remain accepted before/after a child for existing scripts. */
457
+ export function commandOptions(command) {
458
+ return [...(commandDefinition(command)?.options ?? []), ...GLOBAL_OPTIONS];
459
+ }
@@ -0,0 +1,2 @@
1
+ /** Generate static completion source; no shell profiles, network or resource discovery. */
2
+ export declare function completionScript(shell: 'bash' | 'zsh'): string;
@@ -0,0 +1,201 @@
1
+ import { COMMANDS, GLOBAL_OPTIONS, commandOptions, commandTopic, } from './command-schema.js';
2
+ import { PUBLIC_STACK_ADDITIONS } from './capability-catalog.js';
3
+ import { UI_CATALOG } from './ui-catalog.js';
4
+ /** Quote data for shell source. Completion never evaluates user input. */
5
+ function quote(value) {
6
+ return "'" + value.replaceAll("'", "'\"'\"'") + "'";
7
+ }
8
+ function words(values) {
9
+ return values.map(quote).join(' ');
10
+ }
11
+ function nodes() {
12
+ const result = [];
13
+ function visit(topic, definition) {
14
+ result.push([topic.join(' '), commandTopic(topic)]);
15
+ for (const [child, entry] of Object.entries(definition.children ?? {}))
16
+ visit([...topic, child], entry);
17
+ }
18
+ for (const [name, definition] of Object.entries(COMMANDS))
19
+ visit([name], definition);
20
+ return result;
21
+ }
22
+ function choices(definition) {
23
+ if (definition.children)
24
+ return Object.keys(definition.children);
25
+ const positional = definition.positional;
26
+ if (positional?.kind === 'capability')
27
+ return PUBLIC_STACK_ADDITIONS;
28
+ if (positional?.kind === 'component')
29
+ return UI_CATALOG.components.filter((entry) => entry.web).map((entry) => entry.name);
30
+ return positional?.choices ?? [];
31
+ }
32
+ function optionCase(context, option) {
33
+ const patterns = [option.flag, ...(option.aliases ?? [])]
34
+ .map((flag) => quote(`${context}:${flag}`))
35
+ .join('|');
36
+ return ` ${patterns}) _known=1; _canonical=${quote(option.flag)}; _arity=${option.arity ? 1 : 0}; _kind=${quote(option.kind ?? '')}; _choices=(${words(option.choices ?? [])});;`;
37
+ }
38
+ function tables() {
39
+ const entries = nodes();
40
+ const all = [['', undefined], ...entries];
41
+ const lookup = all.flatMap(([context]) => {
42
+ const options = context ? commandOptions(context.split(' ')[0]) : GLOBAL_OPTIONS;
43
+ return options.map((option) => optionCase(context, option));
44
+ });
45
+ const transition = entries.map(([context]) => {
46
+ const parts = context.split(' '), child = parts.pop();
47
+ return ` ${quote(`${parts.join(' ')}:${child}`)}) _context=${quote(context)}; _positions=0; return 0;;\n ${quote(`${parts.length ? 'help ' + parts.join(' ') : 'help'}:${child}`)}) _context=${quote('help ' + context)}; _positions=0; return 0;;`;
48
+ });
49
+ const positional = entries.map(([context, definition]) => {
50
+ const max = definition.children ? 1 : (definition.positional?.max ?? 0);
51
+ return ` ${quote(context)}) _candidates=(${words(choices(definition))}); _kind=${quote(definition.positional?.kind ?? '')}; _max=${max};;`;
52
+ });
53
+ const flags = all.map(([context, definition]) => {
54
+ const options = [...(definition?.options ?? []), ...GLOBAL_OPTIONS];
55
+ const assignments = options
56
+ .filter((option) => !option.hidden)
57
+ .map((option) => {
58
+ const exclude = new Set(option.repeatable ? [] : [option.flag]);
59
+ for (const conflict of definition?.conflicts ?? [])
60
+ if (conflict.includes(option.flag))
61
+ for (const flag of conflict)
62
+ exclude.add(flag);
63
+ if (option.flag === '--json')
64
+ exclude.add('--human');
65
+ if (option.flag === '--human')
66
+ exclude.add('--json');
67
+ const condition = [...exclude]
68
+ .map((flag) => `[[ " $_seen " != *${quote(' ' + flag + ' ')}* ]]`)
69
+ .join(' && ');
70
+ const assignment = `_candidates+=(${words([option.flag, ...(option.aliases ?? [])])})`;
71
+ return ` ${condition ? `if ${condition}; then ${assignment}; fi` : assignment}`;
72
+ });
73
+ return ` ${quote(context)})\n${assignments.join('\n')}\n ;;`;
74
+ });
75
+ return `_anhedral_option() {
76
+ _known=0; _arity=0; _kind=''; _choices=(); _canonical=''
77
+ case "$1:$2" in
78
+ ${lookup.join('\n')}
79
+ esac
80
+ }
81
+ _anhedral_transition() {
82
+ case "$_context:$1" in
83
+ ':help') _context='help'; _positions=0; return 0;;
84
+ ${transition.join('\n')}
85
+ esac
86
+ return 1
87
+ }
88
+ _anhedral_node() {
89
+ _candidates=(); _kind=''; _max=0
90
+ case "$1" in
91
+ ''|'help') _candidates=(${words([...Object.keys(COMMANDS), 'help'])}); _max=1;;
92
+ ${positional.join('\n')}
93
+ esac
94
+ }
95
+ _anhedral_flags() {
96
+ _candidates=(); _kind=''
97
+ case "$1" in
98
+ ${flags.join('\n')}
99
+ esac
100
+ }
101
+ _anhedral_prepare() {
102
+ _needle="$1"; shift
103
+ _context=''; _pending=''; _pending_context=''; _seen=''; _positions=0; _end=0
104
+ _prefix=''; _used_values=()
105
+ local word flag
106
+ for word in "$@"; do
107
+ if [[ -n "$_pending" ]]; then
108
+ if [[ "$word" = '=' ]]; then continue; fi
109
+ _pending=''; continue
110
+ fi
111
+ if [[ "$_end" = 0 && "$word" = '--' ]]; then _end=1; continue; fi
112
+ if [[ "$_end" = 0 && "$word" = -* ]]; then
113
+ flag="\${word%%=*}"
114
+ _anhedral_option "$_context" "$flag"
115
+ if [[ "$_known" = 1 ]]; then
116
+ _seen="$_seen $_canonical"
117
+ if [[ "$_arity" = 1 && "$word" != *=* ]]; then
118
+ _pending="$flag"; _pending_context="$_context"
119
+ fi
120
+ fi
121
+ continue
122
+ fi
123
+ if ! _anhedral_transition "$word"; then
124
+ _positions=$((_positions + 1)); _used_values+=("$word")
125
+ fi
126
+ done
127
+ if [[ -n "$_pending" ]]; then
128
+ [[ "$_needle" = '=' ]] && _needle=''
129
+ _anhedral_option "$_pending_context" "$_pending"
130
+ _candidates=("\${_choices[@]}")
131
+ return
132
+ fi
133
+ if [[ "$_end" = 0 && "$_needle" = --*=* ]]; then
134
+ flag="\${_needle%%=*}"
135
+ _anhedral_option "$_context" "$flag"
136
+ if [[ "$_known" = 1 && "$_arity" = 1 ]]; then
137
+ _prefix="$flag="; _needle="\${_needle#*=}"; _candidates=("\${_choices[@]}"); return
138
+ fi
139
+ fi
140
+ if [[ "$_end" = 0 && "$_needle" = -* ]]; then
141
+ _anhedral_flags "$_context"
142
+ if [[ -z "$_context" ]]; then _candidates+=('--version' '-v'); fi
143
+ return
144
+ fi
145
+ local topic="\${_context#help }"
146
+ _anhedral_node "$topic"
147
+ if [[ "$_positions" -ge "$_max" ]]; then _candidates=(); _kind=''; fi
148
+ }
149
+ `;
150
+ }
151
+ const locals = ` local _context _pending _pending_context _seen _positions _end _prefix _needle
152
+ local _known _arity _kind _canonical _max candidate used duplicate
153
+ local -a _candidates _choices _used_values`;
154
+ /** Generate static completion source; no shell profiles, network or resource discovery. */
155
+ export function completionScript(shell) {
156
+ const header = `# Anhedral ${shell} completion. Source this file after shell completion initialization.\n`;
157
+ if (shell === 'bash')
158
+ return (header +
159
+ tables() +
160
+ `_anhedral() {
161
+ ${locals}
162
+ COMPREPLY=()
163
+ _anhedral_prepare "\${COMP_WORDS[COMP_CWORD]}" "\${COMP_WORDS[@]:1:COMP_CWORD-1}"
164
+ if [[ "$_kind" = 'file' || "$_kind" = 'directory' ]]; then
165
+ local mode='-f'
166
+ [[ "$_kind" = 'directory' ]] && mode='-d'
167
+ while IFS= read -r candidate; do COMPREPLY+=("$_prefix$candidate"); done < <(compgen "$mode" -- "$_needle")
168
+ else
169
+ for candidate in "\${_candidates[@]}"; do
170
+ duplicate=0
171
+ for used in "\${_used_values[@]}"; do [[ "$used" = "$candidate" ]] && duplicate=1; done
172
+ if [[ "$duplicate" = 0 && "$candidate" = "$_needle"* ]]; then COMPREPLY+=("$_prefix$candidate"); fi
173
+ done
174
+ fi
175
+ }
176
+ complete -o filenames -F _anhedral anhedral
177
+ `);
178
+ return (header +
179
+ tables() +
180
+ `_anhedral() {
181
+ ${locals}
182
+ local -a prior
183
+ local i
184
+ for ((i=2; i<CURRENT; i++)); do prior+=("\${words[i]}"); done
185
+ _anhedral_prepare "\${words[CURRENT]}" "\${prior[@]}"
186
+ if [[ "$_kind" = 'file' || "$_kind" = 'directory' ]]; then
187
+ local PREFIX="$_needle"
188
+ if [[ "$_kind" = 'directory' ]]; then _files -/ -P "$_prefix"; else _files -P "$_prefix"; fi
189
+ else
190
+ local -a matches
191
+ for candidate in "\${_candidates[@]}"; do
192
+ duplicate=0
193
+ for used in "\${_used_values[@]}"; do [[ "$used" = "$candidate" ]] && duplicate=1; done
194
+ [[ "$duplicate" = 0 && "$candidate" = "$_needle"* ]] && matches+=("$_prefix$candidate")
195
+ done
196
+ compadd -a matches
197
+ fi
198
+ }
199
+ compdef _anhedral anhedral
200
+ `);
201
+ }